Thttpd manual

1. 名字

thttpd- 是一款小型/快速/非阻塞的HTTP服务程序

2. 概要

thttpd [-C configfile] [-p port] [-d dir] [-dd data_dir] [-r|-nor] [-s|-nos] [-v|-nov] [-g|-nog] [-u user] [-c cgipat] [-t throttles] [-h host] [-l logfile] [-i pidfile] [-T charset] [-P P3P] [-M maxage] [-V] [-D]

3. 描述

thttpd 是简单的，小型，快速而安全的 HTTP 服务程序。 没有许多特别的特征，但是对大多数web它所提供的功能已经足够, 它如功能齐全的servers (Apache, NCSA Netscape) 一样的迅速，而且它有一极有用的特征 (URL-traffic-based throttling) 这是其他的server没有的。

4. 选项

-C

指定一个可读的配置文件可以在其中设置所以的指令行标志，细节如下。

-p

设定一个交互的端口数字来监听，默认值是 80 ，这一标志在配置文件中的选项名字是 " port ",在config.h中选项是是 DEFAULT_PORT

-d

对 chdir()指定一个目录，用来启动进程。这只是为了提供一个便捷方式 - 你可以比较容易地在shell 脚本中写一个cd命令来唤醒进程 这一面标志在c配置文件中的选项名字是" dir",在config.h 选项是WEBDIR USE_USER_DIR 。

-r

在初始化值时执行 chroot()能够限制文件访问程序的当前目录。如果 - r 是在默认下编译的，那么-nor 可以使其失效。下面有详细的介绍。这一标志在配置文件中的选项名字是 " chroot" 和 " nochroot",在 config.h文件中 选项是 ALWAYS_CHROOT

-dd

用来指定一个目录执行chdir()，如果你还没有chrooting, 你可以在-d标志后加上单一的chdir()，如果已经chrooting则可以把网页文件放入子目录，而不比把它们和chroot tree混在一起。这一标志在配置文件中的选项名字是 " data_dir" 。

-nos

不要做显式的软链接检查。

通常情况下， thttpd 显式地在文件名中扩展了所有的软链接,以此来

检查驻留在初始文件树里的最终路径。

如果你想要避开这些检查而节省一些处理器时间,你就可以使用

那 -nos标志,尽管这并不被推荐。但是,注意,如果你正在使用 chroot 选项，那么对软链接的检查就是不必要的因而被停止了 , 因此节省那些处理器时钟周期的保险办法是使用 chroot 。

这一标志在配置文件中的选项名字是 " symlinkcheck" 和 " nosymlinkcheck" 。

-v

做小开销的虚拟动作，如果-v是在编译时缺省配置的，那么-nov可以使其失效，下面有详细介绍。这一标志的 config- file的选项名字是 " vhost" 和 " novhost", config.h 选项是ALWAYS_VHOST 。

-g

使用全局密码文件。这意味着，在这个目录树下的每个文件都是被在树顶部的单独.htpasswd文件所保护的。不管怎样，.htpasswd文件的语义是相同的。如果该选项被设置了，但在目录顶层却没有.htpasswd文件的话，那么thttpd进程可能没有被事先设置成一个局部.htpasswd文件，而且，如果这个也不存在的话，那么就表示该文件是没有任何密码的。如果-g被缺省编译了，那么-nog可以使其失效。这个标志在配置文件中的选项名是"globalpasswd"和"noglobalpasswd",在config.h中 的可选项是ALWAYS_GLOBAL_PASSWD。

-u

指定当以root初始登陆后切换到哪一个使用者。默认值是 " nobody "。这一标志在配置文件中的选项名字是 " user",在config.h中是DEFAULT_USER 。

-c

为 CGI 指定一个通配符, 举例来说如 "**.cgi"或 "/cgi-bin/*".细节如下。这一标志在配置文件中的选项名字是 " cgipat",在config.h 中是 CGI_PATTERN 。

-t

指定一个文件来结束设置。细节如下。这一标志在配置文件中的选项名字是 " throttles "

-h

为多用户环境指定一个绑定的主机名。缺省情况是，把所有的主机都绑定在本地机器上。下面是详细介绍。这一标志在配置文件中的选项名字是 " host ",在 config.h中是 SERVER_NAME 。

-l

指定一个日志文件。如果-l参数没有被指定，那么thttpd通过syslog()进行日志记录。如果"-l /dev/null"被指定了，那么thttpd就不会再进行日志记录了。这个标志的配置文件选项名是"logfile"。

-I

指定一个写进程号的文件。如果没有文件被指定，那么就没有进程号被写入了。你可以使用这个文件给thttpd发送信号。看下面的详细介绍；这一标志在配置文件中的选项名字是 " pidfile" 。

-T

指定一个使用MIME文本类型的字符集。缺省情况是iso-8859-1。这个标志在配置文件中的选项名是"charset",在config.h 中是DEFAULT_CHARSET。

-P

指定一个能够返回所有响应的P3P秘密服务头。详情请看http://www.w3.org/P3P/带有字符串的Thttpd不会做任何事情，除非把它放到P3P中响应头部。这个标记的配置文件选项命名为“P3P”。

-M

指定秒钟数，在"Cache-Control: max-age"环境下被使用。对于所有的响应，头部被返回。一个与此等价的"终止"头部也随之生成。缺省情况是没有Cache控制 或者终止头部，这对大多数网站来说，是非常理想的。这个标志的配置文件选项名是"max_age"。

-V

表示现在的版本信息

-D

这个标志最初仅仅用来作为一个调试标志，但是，在这里仍然有提一下的价值。因为它所做的这些事情的其中一件是阻止thttpd在后台自我复制。取而代之的是它象一个正规程序一样地在前台运行。在一些shell脚本中，你希望如果被封装的thttpd存在的话，它就会重启，如果你想运行这样的thttpd，应用这个标志是很有必要的。

5. 配置文件

所有的指令行的选项也能在一个配置文件中设定。 使用一个配置文件的一个优势是，文件能被改变，而且 thttpd 将根据新的定重新启动。 配置文件的语法很简单, 一系列的被空格分开的 选项 " 或 "选项=价值" 。 选项名字和他们对应的指令行标志将被一起列出。

6. CHROOT

chroot() 是一个系统呼叫用来限制程式对当前目录和目录下的文件系统的查看。 它使远程用户不可存取开始的目录以外的任何文件。这种限制是通过子程序继承得到的，因此， CGI 程序也得到这种权限。 这是非常强大的安全级别而被推荐。 唯一的缺点是只有根用户能呼叫 chroot() ，因此，程序必须是由根用户启动。然而, 在完成设定初值后做的它会放弃根用户的存取权限而改为另一非根用户权限,因此这是安全的。

程序也能通过编译来配置成总是执行 chroot()而不需要-r 选项。注意，和一些其他的servers, 像NCSA httpd相比较，设定一棵目录树用于使用 chroot(), 包括创造一串特别的目录并且在其中复制各种不同的文件。 thttpd 是比较容易的, 所有你必须做的只是确定每个shells有效并且确保,CGI 程序和脚本所使用的配置文件是可用的。如果你的CGI无效, 或你限定让所有的 CGI程序以一定的编译语言如 C 和静态联编,那么你可能完全不需要做任何配置了。

但是，你应该做的一件事情是告诉系统日志有关 chroot tree的信息,所以 thttpd 仍然能产生系统日志信息。通过核对你系统的系统日志指南来指导你该如何做这些。 在 FreeBSD 中你可以把日志放入 /etc/ rc.conf:

syslogd_flags="-l /usr/local/www/data/dev/log"

用你自己的 chroot tree路径名称替换。不要烦恼有关创造日志套接字， 系统日志会自己去做做这些。 (你可能需要产生 dev 目录)。 在 Linux 中标志是 -a代替 -l, 而且可能有其他的不同。

有关的 config.h 选项: ALWAYS_CHROOT。

7.  CGI

thttpd 支持CGI 1.1 规格

为了使CGI程序正常运行起来，它的名字也一定相配于在编译时被指定的式样或在指令行通过 -c标志指定。这是一个简单的shell风格的文件名式样。 你能使用 * 相配任何的字符串不包括一个斜线, 或用** 相配包括斜线的任何字符串, 或用? 相配任何单独的符号。你也能通过隔离符 |来使用多个模式.这些式样拿来检查引入网址的文件名部份。 不要忘记提供任何的通配字符特性以便让shell来作为参考。

限制CGI 程序放置到一个单一的目录使地址管理者查看它们来检测安全漏洞, 而且这点被强烈地推荐。 如果有个别你信任的使用者,你也能使他们可以进入目录。

如果没有 CGI 式样在这里或者编译时被指定, CGI程序将完全无法运行。如果你考虑安全级别而想要使CGI失效,那么你要做的只是在配置文件中注释掉它的模式并且不要和-c标志一起启动进程。

注意: 当一个 CGI 程序运行的时候的当前工作目录是 CGI程序所在的目录。 这不在 CGI 1.1 规格中，但是这是大多数的其他 HTTP服务器所要求的。有关的 config.h 选项: CGI_PATTERN ， CGI_TIMELIMIT ， CGI_NICE ， CGI_PATH ， CGI_LD_LIBRARY_PATH ， CGIBINDIR。

8.  基本证明

作为编译时的一个选项基本鉴定是有效的。如果可以, 它会使用该目录中的一个密码文件来使其被保护, 默认称为.htpasswd。这一个文件被格式如一般的由冒号分开的username/encrypted-password 对，并以换行来划分每条记录。这种保护不继续到子目录。 有效程序 htpasswd(1)包括了帮助产生和修正.htpasswd 的文件。有关的 config.h 选项: AUTH_FILE。

9.  终止

终止文件使你可以设定在URL或者URL域上的最大比特率。 你能随意地设定最小的速率。 终止文件的格式非常简单。以#开始的是注释,该行的其它部分被忽略。 空白行也被忽略。 行的其它部分应该由一个式样组成，空白和一个数字。 该式样是一个简单的shell风格的文件名式样, 使用 ?/**/*, 或被|分隔的多种式样。

文件中的数字是位元速率,指定的每秒单位字节。 比如a v.90个调制解调器大约是压缩的 5000 B/ s ，一个 double-B-channel ISDN 大约 12800个 B/s ，而一条 T1 线是大约 150000个 B/s 。 如果你想要设定最小的比率, 使用数字-数字。

例子:

# throttle file for www.acme.com

**              2000-100000 

# limit total web usage to 2/3 of our T1,

# but never go below 2000 B/s

**.jpg|**.gif   50000   # limit images to 1/3 of our T1

**.mpg          20000   # and movies to even less

jef/**          20000   # jef's pages are too popular

终止是根据在终止文件中的所有模式来检查引入的每一个式样网址文件名。 服务器累积并统计每个模式最近占用了多少带宽.(平均值) 如果一个网址相配一个已经超过它的指定界限的模式,那么数据的返回将被减慢 ,甚至在每个区段之间中止。 如果那是不可能的 ( 举例来说对于 CGI 程序) 或者带宽已经极大的超过极限，那么服务器将返回一传特殊的文字 ' try again later'. 最小的比特率也是同样的方法实现。 如果太多人同时地尝试连接, 阻塞可能减慢每个连接很多以致真的不可用。 此外, 所有的那些连接将阻塞服务器,用光文件柄和连接位置。设定最小的比特率的话，如果超过某个特定的点你也不需要烦恼。服务器返回 ''try again later" ，而且连接无法开始。

因为阻塞一个请求使用的cpu和处理它所用的一样多，所以没有为终止设定一个最大的连接/ 秒值。 也没有规定终止同时连接某一网址的数字基准。然而你能通过在启动thttpd之前设置操作系统每个处理文件描述符的极限来非常容易地控制整个连接到服务器的数字。确定设定的是硬界限而不是软界限。

10. MULTIHOMING

MULTIHOMING意思是使用一部机器服务多个 hostnames 。举例来说，如果你们是英特网供给者，而且你想要让你的所有客户持有定制的网络地址,你可能有 www.joe.acme.com ， www.jane.acme.com 和你自己的 www.acme.com,全部运行在相同的物理硬件上。 这一个特征也即是 " 虚拟主机 " 。 有三个建立这的步骤。

 

一,对于所有的 hostnames 作 DNS 进入。 当前的方法如下, 被 HTTP/1.1 允许, 是使用 CNAME 别名, 像如此:

www.acme.com IN A 192.100.66.1

www.joe.acme.com IN CNAME www.acme.com

www.jane.acme.com IN CNAME www.acme.com

然而，这对较旧的 HTTP/1.0 浏览器是不兼容的。如果你想要保持兼容, 有一个备选的方法：使用Ａ标志改为,每个以一个不同的 IP 住址, 像下面:

www.acme.com IN A 192.100.66.10

www.joe.acme.com IN A 192.100.66.200

www.jane.acme.com IN A 192.100.66.201

因为它使用额外的 IP 住址，占用了略微缺乏的资源，所以这不是很好。 但是如果你想使用较旧的浏览器的人也能够访问你的站点,你仍然必须这样做。

第二步骤。 如果你正在使用MULTIHOMING的近代 CNAME 方法,那么你可以跳越这一个步骤。另外的方式是使用旧式的多重ＩＰ地址，你需要为额外的地址设定 IP 别名或多样的接口。你能使用 ifconfig(8)' s 别名命令告诉机器应答所有的不同 IP 住址。 例如:

ifconfig le0 www.acme.com

ifconfig le0 www.joe.acme.com alias

ifconfig le0 www.jane.acme.com alias

 

如果你的操作系统的 ifconfig 版本没有一个别名指令, 或许你运气不好。

第三,你必须设置 thttpd 来处理多个的主机。 最容易的方法是使用 -v标志 , 或 ALWAYS_VHOST config.h 选项。使用CNAME 多主机租贷或复 IP 的多主机租贷。 它所做的是送每个收到的请求到一个以 hostname 为基础的已被绑定的子目录。为了实现这些 ,你需要在thttpd运行的目录中建立这些子目录。 由上方的例子,你可以这样做:

mkdir www.acme.com www.joe.acme.com www.jane.acme.com

如果你正在使用旧式的多样- IP 多主机租贷,你也应该引用一些名字到数值地址的符号链接, 像如此:

ln- s 的 www.acme.com 192.100.66.1

ln- s 的 www.joe.acme.com 192.100.66.200

ln- s 的 www.jane.acme.com 192.100.66.201

这使较旧的 HTTP/1.0浏览器能找到正确的子目录。

如果你正在使用复- IP 的多主机租贷，有一个可选的第三步骤:为每个hostname 运行一个独立的 thttpd 程序, 并通过－h标志绑定。这就给了你较多的灵活度,因为你能为每个不同目录中的这些程序,指定不同的终止文件等，例如:

thttpd -r -d /usr/www -h www.acme.com

thttpd -r -d /usr/www/joe -u joe -h www.joe.acme.com

thttpd -r -d /usr/www/jane -u jane -h www.jane.acme.com

 

但是记得, 这多样- 程序方法不与 CNAME 多主机租贷合作 - 对于那，你一定一起使用单一 thttpd 程序通过 -v 旗子。

11. 订制错误

thttpd 允许你为各种不同的 HTTP 错误定义你自己习惯的错误页。 每个错误数字有一个独立的文件并且全部储存在一个特别的目录中。在网络目录树的顶端目录名字是 " errors" 。 错误文件应该叫做 " errNNN.html", NNN 是错误数字。举例来说，为编号为401的验证失败的错误订制一个习惯的错误页,你会把你的 HTML 放入文件 " errors/err401.html" 。如果对给定的错误数值没有找到订制的错误文件,那么将产生一般的内建错误页。

如果你正在使用虚拟主机选项,你也能对于每个不同的虚拟主机使用不同的习惯错误页。 在这情况下你把另外的 " errors" 目录放入虚拟主机网网络树的顶端。 thttpd 将会先查看虚拟主机的错误目录, 然后查看服务器扩展错误目录，如果那些都没有一个适当的错误文件，它将会产生内建的错误文件。

12. 非地方 REFERERS

有时网上另外的一个网站将会插入他们的 HTML 文件到你图像文件,基本上意谓他们正在偷你的带宽。 你能通过使用非局部的相关过滤来阻止他们做这些。由这个选项，特定的文件只能经由一地方相关的网站来取得。 这些文件必须由一个本地网页来引用。 如果在一些其他网站上的网页文件想取得相关文件将会被阻止。这一特征有三个配置文件变量:

urlpat

网址的通配模式需要一个本地参考。 这是典型的图像文件, 声音文件等等。 例如:

urlpat=**.|**.gif|**.au|**.wav

对于大多数的位置，这样的一个设定就是你需要能够提到过滤。

noemptyreferers

默认的 , 请求全然没有参考提到,或者是无效的参考, 或参考但是没有明显的 hostname 提到被允许。通过这个变量的设置,如此一类的请求将被阻止。

localpat

一个指定本地主机或主机的通配符模式。 这用来测定查阅的是否是主机。 如果未指定就由默认的来指定实际的本地主机。

13.  SYMLINKS

thttpd 对符号联编是很讲究的。在递交一份文件之前，它首先检查路径中的每一个组成去看是否是一个符号链接，并且竭尽全力的去扩张他们去获得他们最终的实际文件名。就象检查链接服务器的上层目录“..”, 和绝对的 symlinks.( ones that start with a  /) 。 这些被当作安全漏洞禁止,所以服务器返回错误页。这意谓你不能通过一串字符链接设置你的网页目录指向个人的使用者的主页目录 。相反的你在附近这样做的另一个方法-使用者网站目录确实是主要的网站目录的子目录，而且在每个使用者的主目录中有一个符号链接指向它们真正的网站目录。

CGI 模式也影响 它通过完全扩展的文件名获得匹配。 所以，如果你有一个单一 CGI 目录，但是其中放入了一个符号链接用来指到别处,那么它将不能工作。CGＩ程序将会被当做一个一般的文件并返还到客户而不运行。

14. 许可

thttpd 对文件权限也是很严格的。它希望数据文件 (HTML,图像) 是世界可读的。 可读对于可以运行thttpd程序的组来说是不足够的- thttpd 会对可读字节做明确的检查。以至没有人会对一个没有设置完全可读但是仍然可被HTTP服务器读取的文件而感到惊讶。

相同的逻辑也适用于目录。关于标准的 Unix的" ls" 指令, 如果它的阅读一点点是， thttpd 只将会让你审查在目录下的内容如果它的可读位打开了， 但是对于数据文件,就必须设置成是完全可读，而不只是组可读。

thttpd 对于数据文件的执行位设置为 *off*。一个可运行的文件但是并不匹配 CGI模式可能是一个脚本或者程序被偶然防在了错误的目录。允许人获取文件的内容可能是一个安全漏洞,因此这被禁止。 当然如果一个可运行的文件*does* 相配 CGI 式样,那么它将做为 CGI运行。

概括的说，数据文件应该是模态 644(rw-r--r--), 目录应该是 755(rwxr-xr-x) 如果你想要允许索引，而设置为711(rwx--x--x) 将不允许索引, 而且 CGI程序的模态应该设为 755(rwxr-xr-x) 或 711.(rwx--x--x)

15. 日志

thttpd 由 syslog（3）来做它的所有日志。它使用的设备是可配置的。除了错误信息，只有很少的日志记录产生。所有的非常相似于CERN 通常的日志格式:

Aug  6 15:40:34 acme thttpd[583]: 165.113.207.103 - - "GET /file" 200 357

Aug  6 15:40:43 acme thttpd[583]: 165.113.207.103 - - "HEAD /file" 200 0

Aug  6 15:41:16 acme thttpd[583]: referer http://www.acme.com/ -> /dir

Aug  6 15:41:16 acme thttpd[583]: user-agent Mozilla/1.1N

包中包括一个脚本用来用来把日志入口信息转换为兼容CERN的文件。注意 thttpd 不能将数值的 IP 住址转换成域名。 这既节省了时间也可作为一个小型的安全措施(数值的住址是比较难骗过的)

有关的 config.h 选项: LOG_FACILITY。

如果你要将日志写入到某一个文件中, 你能使用那 - l 指令行标志。 但是注意错误信息仍然进入 syslog。

16. 信号

thttpd 处理一些信号, 你可以通过标准的 Unix  kill(1) 指令传送:

INT,TERM

这些信号告诉 thttpd 立刻停止。 任何的请求都将失败。

USR1

这信号告诉 thttpd 停止一旦它完成了当前的所有请求。 除此之外，它用来接受新的连接的网络端口也立刻关闭, 这意谓新的 thttpd 能被立刻开始。

USR2

这信号告诉 thttpd 立刻进行syslog 信息的统计,取代是每小时规律地更新。

HUP

这信号告诉 thttpd 关闭并且重新打开它的 (非 syslog)日志文件,举例来说如果你替换了日志想要它开始新的一个。这是稍微机智的正确建立, 举例来说如果你正在使用 chroot()那么日志文件一定是在 chroot 树里面,但是它一定是可行的。