Basic Installation of Pegasus
Contents- 1.0.0 Installing
httpd
andmon
- 1.1.0 Install
httpd
- 1.2.0 Install
mon
- 2.0.0 The First Goal
- 2.1.0 Look sample directory tree
- 2.2.0 The first goal
- 3.0.0 Virtual User
web
- 3.1.0
/adm/users
- 3.2.0
/usr/web
- 4.0.0 Configurations
- 4.1.0
/sys/lib/httpd.conf
- 4.2.0
/lib/namespace.httpd
- 4.3.0
/sys/lib/httpd.rewrite
- 4.4.0
/sys/log/http
and/sys/log/blacklist
- 5.0.0 Web Document
- 5.1.0 httpd root
- 5.2.0 Web pages for regular users
- 5.3.0 Access control
- 5.4.0 CGI
- 5.5.0 Real and virtual hosts
- 6.0.0 Run Pegasus
- 6.1.0 Run Pegasus using “mon”
- 6.2.0 Confirm Pegasus does service
- 6.3.0 Updating
Here I will explain how to install Pegasus with assumptions:
- You are the host owner with account name “bob”.
- You have a system user with account name “alice”.
- Run Pegasus in server mode.
- Run Pegasus as user “web”.
Installing httpd
and mon
Install httpd
1. Get Pegasus 2.8 from
http://plan9.aichi-u.ac.jp/netlib/pegasus/pegasus-2.8.tgz2. Unpack
term% gunzip pegasus-2.8.tgz term% tar -xf pegasus-2.8.tarthen a directory “
pegasus-2.8
” will be created in the directory in which you executed “tar”.Let this directory be “
$pegasus
” in the explanation below.
3. Compile
term% cd $pegasus/httpd term% mk4. Install
The default installation place is:
/usr/local/bin/$objtypeCreate the directory and execute:
term% mk install
Install mon
In the same way, you can install “mon”.
term% cd $pegasus/mon term% mk install
The First Goal
Look sample directory tree
In the package, you look example in directory $pagasus/example
.
The directory tree is:
example/lib/ example/lib/namespace.httpd example/sys/ example/sys/lib/ example/sys/lib/httpd.conf example/sys/lib/httpd.rewrite example/sys/log/ example/sys/log/blacklist example/sys/log/http example/usr/ example/usr/alice/ example/usr/alice/web/ example/usr/alice/web/doc/ example/usr/alice/web/doc/index.html example/usr/bob/ example/usr/bob/www/ example/usr/bob/www/doc/ example/usr/bob/www/doc/index.html example/usr/web/ example/usr/web/README example/usr/web/bin/ example/usr/web/bin/386/ example/usr/web/bin/rc/ example/usr/web/dev/ example/usr/web/env/ example/usr/web/etc/ example/usr/web/etc/nonce/ example/usr/web/fd/ example/usr/web/lib/ example/usr/web/mnt/ example/usr/web/proc/ example/usr/web/rc/ example/usr/web/rc/lib/ example/usr/web/sys/ example/usr/web/sys/lib/ example/usr/web/tmp/
The first goal
The first goal will be to let the following two files be shown in your browser.
/usr/alice/web/doc/index.html
/usr/bob/www/doc/index.html
Virtual User web
Pegasus runs as user “web” and does service as the user.
You must not give password for user “web
”.
/adm/users
- Add a user “
web
” to “/adm/users
”
- Add a group “
webu
” and the group members (web
,alice
,bob
) to “/adm/users
”
/usr/web
The directory “/usr/web
” is a default base directory on which Pegasus configures namespace.( You can use other directory. Look "
/sys/lib/httpd.conf
".)term% mkdir /usr/web term% chmod 775 /usr/webDon't let owner of “
/usr/web/
” be “web
”.
Create empty directories under “/usr/web/
”. The goal is like the followings*.
d-rwxrwxr-x bob bob ..... /usr/web/bin/386 d-rwxrwxr-x bob bob ..... /usr/web/bin/rc d-rwxrwxr-x bob bob ..... /usr/web/dev d-rwxrwxr-x bob bob ..... /usr/web/env d-rwxrwxr-x bob bob ..... /usr/web/etc d-rwxrwx--- bob web ..... /usr/web/etc/nonce d-rwxrwxr-x bob bob ..... /usr/web/lib d-rwxrwxr-x bob bob ..... /usr/web/mnt d-rwxrwxr-x bob bob ..... /usr/web/proc d-rwxrwxr-x bob bob ..... /usr/web/rc/lib d-rwxrwxr-x bob bob ..... /usr/web/sys/lib d-rwxr-xr-x bob bob ..... /usr/web/tmpwhere “bob” is your account name. Take notice of the permission bits and the group of “
/usr/web/etc/nonce/
”.
You have the replica under “$pegasus/example/usr/web/
”. Therefore you may copy the replica to “/usr/web
”.
The copy is easy if you use my tool “cpdir”. You can get “cpdir” from http://plan9.aichi-u.ac.jp/netlib/cmd/
.
term% cpdir -mv $pegasus/example/usr/web /usr/weband then
term% chmod 770 /usr/web/etc/nonce term% chgrp webu /usr/web/etc/nonce
Note that:
- Don't set owner of these directory to be “web”. Permit “others” to read and execute.
- Directory “
/usr/web/etc/nonce
” must be given full access permission to user “web”.
- File tree under “
example/usr/web/
” is configured for CGI, therefore there are needless directories if you do not use CGI. However I think they are harmless.
Configurations
Pegasus use following files for configuration.
/sys/lib/httpd.conf
/sys/lib/httpd.rewrite
/lib/namespace.httpd
Note that you have already “/sys/lib/httpd.rewrite
” and “/lib/namespace.httpd
” of official httpd. It is wise to make a backup of these files.
The templates are in “$pegasus/sample
”. Copy them to the appropriate place:
term% cd $pegasus/sample term% cp sys/lib/httpd.conf /sys/lib/httpd.conf term% cp sys/lib/httpd.rewrite /sys/lib/httpd.rewrite term% cp lib/namespace.httpd /lib/namespace.httpd
/sys/lib/mimetype
. However you probably need not touch this file.
/sys/lib/httpd.conf
Take a look at “/sys/lib/httpd.conf
”.The file is for fine tuning of Pegasus.
Lines beginning with “#” are comments.
Note that by a line:
charset utf-8By this line, the servers char set is set to utf-8.
This means you must write all text documents in utf-8 (see NOTE below).
You need not change the default values in this file. The tuning is after you have monitored the performance of the server.
look http://www.w3.org/TR/html4/charset.html#h-5.2.2 for this topic.
/lib/namespace.httpd
Take a look at “/lib/namespace.httpd
”. The contents will bebind -a /usr/web/bin/$cputype /bin bind -a /usr/web/bin/rc /bin bind /sys/lib /usr/web/sys/lib bind /lib /usr/web/lib bind /bin /usr/web/bin bind /rc/lib /usr/web/rc/lib bind -c #e /usr/web/env bind #c /usr/web/dev bind /proc /usr/web/procNot all will be required.
Note that the line:
bind /sys/lib /usr/web/sys/libwill make all files under “
/sys/lib
” accessible via CGI. Especially you should note that some secret files such as “/sys/lib/ssh
” and “/sys/lib/tls
” might be there. They should be protected against reading by others
.
CGI environment configured in “/lib/namespace.httpd
” will be inherited to real host, virtual hosts, and regular users. Therefore you should be careful enough.
Although the content is configured for CGI and the content might be too much for regular CGI service, I think the configuration is harmless.
/sys/lib/httpd.rewrite
Suppose you are bob who administrates real host documents, and you want to locate documents under “/usr/bob/www/doc
”. Then the following single line (the last line in httpd.rewrite
) is enough for most cases.# # syntax: prefix replacement # parsed by splitting into fields separated by spaces and tabs. # Anything following a # is ignored. # # Pegasus extension for virtual host # `*' prefixed items will be bound to web root # # Home page for IP based virtual host. Don't foreget the IP of plan9 #http://car */usr/carol/www #http://202.250.160.122 */usr/carol/www # Redirection to another site #/~emili http://plan9.bell-labs.com # Httpd root of real host is "/usr/bob/www" / */usr/bob/www
This configuration stands on the assumption that bob has web documents for his real host in /usr/bob/www/doc/
.
You need not configure regular users web pages (i,e,/usr/alice/web
for alice
). They are in service if the users have web pages.
If you do want to configure more complicated hosting service, look /sys/lib/httpd.rewrite
.
/sys/log/http
and /sys/log/blacklist
Before invoking Pegasus, create log files.Access log file of Pegasus is
/sys/log/http
. (NB: not /sys/log/httpd
)You will find brute client IP in
/sys/log/blacklist
.If you find IPs that you don't think brute in blacklist, you may loosen the parameter
maxconnect
in /sys/lib/http.conf
.
Web Document
httpd root
The distinct feature of Pegasus is that it is running in confined name space.
Assume that user “alice” have her web document in /usr/alice/web/doc
, then Pegasus sees the document in /doc
. The path /usr/alice/web
is the boundary that Pegasus can scope. Pegasus is running inside the boundary when responding request to documents of alice. We call the boundary “httpd root”, which is the key concept to understand Pegasus.
Web pages for regular users
Httpd root for regular user “alice” is /usr/alice/web/
.
The permission should be
d-rwxr-x--- M 73622 alice web 0 Aug 13 2007 /usr/alice/webif you want to protect your files under the directory against other regular users.
Her document root is /usr/alice/web/doc/
.
d-rwxr-xr-x M 73622 alice alice 0 Aug 31 2007 /usr/alice/web/docThen you should be able to look her document by accessing
http://your.server.com/~alicefrom your browser.
You need not other setting for regular user's web page.
Having /usr/alice/web/doc/
is enough for the service. (of course you need the contents in /usr/alice/web/doc/
)
Be ware:
A url reference “http:/bar” in the document of alice denotes “http://realhost/bar” by definition, and not “http://realhost/~alice/bar”.
Thereby, if alice wants to refer a file in her document root, she must write like “http:/~alice/bar”.
Access control
If alice needs access control, alice needs to have control files in/usr/alice/web/etc/allow # for IP based control /usr/alice/web/etc/passwd # password based controlPegasus supports both Basic and Digest authentications.
Look Pegasus 2.2 manual for details.
CGI
For CGI service, alice must have
/usr/alice/web/etc/handlerTwo lines will be enough in most cases:
*.cgi text/html + $target *.html text/html 0 $targetA file with suffix “
.cgi
” or “.html
” in alice's document space is a CGI programs if it is executable for user web
.Files with suffix “
.cgi
” are so called CGI files of other web servers such as Apache.On the other hands, files with suffix “
.html
” enables more handy format.CGI handler of Pegasus is very powerful. If you want to know other type of CGI, look hander in Pegasus 2.2 manual.
Pegasus does not support special directory such as “cgi-bin
”. You can locate CGI program anywhere in document space.
Alice can add her own tools for CGI in directories:
/usr/alice/web/bin/rc /usr/alice/web/bin/386
All CGIs that is running in Pegasus see the document root as /doc
and the CGI is running as user web
.
This is true not only for regular users but also real host and virtual host.
That is, both Pegasus httpd and Pegasus CGI is running in confined name space (sandboxed name space) without using CGI wrapper such as suEXEC, cigwrap and SBOX in unix world.
Directories listed below is probably enough for alice to do CGI.
d-rwxrwx--- M 73622 alice web 0 Aug 13 2007 /usr/alice/web d-rwxr-xr-x M 73622 alice webu 0 Oct 23 2006 /usr/alice/web/bin d-rwxrwxr-x M 73622 alice alice 0 Aug 31 2007 /usr/alice/web/doc d-rwxrwxr-x M 73622 alice alice 0 Aug 31 2007 /usr/alice/web/etc d-rwxrwxr-x M 73622 alice webu 0 Aug 13 2007 /usr/alice/web/log
Fig.1: Basic directory structure of Pegasus
You may need log directory for debugging CGI. The directory is seen as/log
in CGI.Temporal working directory is automatically provided as ram disk. The directory is seen as
/tmp
in CGI. The /tmp
is private to the CGI and will be removed automatically when the CGI is finished.
The is a special file /tmp/.../
. Don't touch the file.
Real and virtual hosts
Basic directory structures and the roles of Pegasus are the same among real host, virtual host, and regular users.
Hence, what I explained in regular users is also true for both real host and virtual hosts.
The difference is in that we must explicitly write the directories for real host and for virtual hosts in the file /sys/lib/httpd.rewrite
.
Here is my live example:
# syntax: prefix replacement # parsed by splitting into fields separated by spaces and tabs. # Anything following a # is ignored. # # prefix is a literal string match which is applied to each # file prefix of each url. The most specific, ie longest # pattern wins, and is applied once (no rescanning). # Leave off trailing slash if pattern is a directory. # # If replacemant is a url, a "Permanently moved" message is returned. # # Home page for virtual host. don't foreget IP of plan9 http://plan9 */usr/arisawa/www https://plan9 */usr/arisawa/www http://202.250.160.122 */usr/arisawa/www https://202.250.160.122 */usr/arisawa/www http://cpa */usr/cpa/www # Redirection to another site #/~carol http://plan9.bell-labs.com / */usr/arisawa/http
My machine named ar
supports:
- real host (
http://ar.aichi-u.ac.jp
)
- IP based virtual host (
http://plan9.aichi-u.ac.jp
)
- name based virtual host (
http://cpa.aichi-u.ac.jp
)
- regular users (
http://ar.aichi-u.ac.jp/~arisawa
)
/usr/arisawa/http/doc
which can be accessed by the URLhttp://ar.aichi-u.ac.jpMy Plan9 pages are in
/usr/arisawa/www/doc
. The URL ishttp://plan9.aichi-u.ac.jpwhich is an IP based virtual host. The IP address is
202.250.160.122
.Hence, we should add a line
http://202.250.160.122 */usr/arisawa/wwwso that we allow client to access using the IP
http://202.250.160.122For real host, Pegasus takes care of the IP. Thus you can access to
ar
byhttp://202.250.160.40without the IP in
/sys/lib/httpd.rewrite
.
Virtual hosts cannot have user's URL, that is, URL such as
http://cpa.aichi-u.ac.jp/~foois intentionally disabled.
Pegasus support https. They works uniformly for real host, virtual hosts and regular users.
Likewise Basic and Digest authentication works uniformly.
The uniformity comes from the uniformity of basic directory structure of httpd space of Pegasus.
Run Pegasus
Run Pegasus using “mon”
Executeterm% b=/usr/local/bin/$cputype term% $b/mon -du web $b/httpd -suMand confirm by “ps” command that “mon” and “httpd” is really running.
The process owner should be “bob” and “web” respectively.
To restart httpd, excute
Kill httpd | rcthen mon will automatically restart the httpd.
Confirm Pegasus does service
Try to access using a browser and take a look at “/sys/log/http
”.
Updating
You might find “pegasus-2.8a”, “pegasus-2.8b”, ... inhttp://plan9.aichi-u.ac.jp/netlib/pegasus/Those are bug fix versions to Pegasus 2.8.