ShellBox Mini-HOWTO

Shellbox Mini-HOWTO

(C) 2002 Amir Malik.
http://amir142.dhs.org/


Picking a Box
=============

One of the most important things is choosing a fast and stable computer
system to run the shell server on. When picking a computer, you need
to think how many simultaneous users you plan to support, and how many
and what kinds of services you will be running. You need to plan how
many and what speed of CPUs you will need, how much RAM will be needed,
hard disks, mirroring (RAID), etc.

I cannot prescribe an ideal server configuration because it would be
impossible to take into account every miniscule detail of server
performance for every user. It is suggested that you take a look at
your current servers and see how they are currently performing, and
see how you could combine/add hardware pieces to maximize their
performance. Or you could go out and buy a server!

Usually, any modern desktop computer with at least a quarter gigabyte of
RAM, half a gigahertz of CPU power, and several gigabytes of disk space
should be able to handle a starter's shell hosting needs.


Picking a Distribution
======================

The most important thing in running a shell server is choosing the right
distribution. Many people believe that a commercially-supported one is
the right choice. This is usually not the case. If you plan on running
a shell server, you need to choose a distribution that you are comfortable
working with, and one that you have experience with. Whether it be
Slackware, Debian, RedHat or Caldera, you should know how to use its
package management system.

For example, if you have only worked on RedHat systems, or most of your
Linux experience is on a RedHat system, you should choose RedHat as your
base distribution. When choosing a distribution, make sure that it is
recent (not more than six months old), and make sure that there is an
active community that supports it, whether it be commercial or not.

I recommend picking a distribution that uses up-to-date technologies
such as PAM (Pluggable Authentication Modules). Remember to choose
a system that will make it easy for you to upgrade the kernel and
software in the near future.


Installing the Distribution
===========================

When installing the base distribution, make sure you do a custom install
with minimal packages installed. Ideally, your base system should not
exceed half a gigabyte. Do NOT install any of the following packages:
- HTTP/FTP servers (Apache, ProFTPD, etc.)
- XFree86 or any related applications (xfree86-libs are ok to install)
- window managers, or any apps that need a windowing system, later you
  may wish to install VNC (Virtual Network Computing) to remotely access
  your desktop; not recommended
- useless applications that aren't necessary for a shell/web server


In a shell environment the general partitioning scheme can be used:

/boot		first partition (5-20MB in size); keeps current kernel
		as well as any backup kernels you may have
/home		largest partition (at least 60% of total disk); this
		is where user directories will be located; you may also
		choose to store user's mail in their home directories,
		thus eliminating the need for a large /var partition
/var		this is where the mail/news spools are kept, if you
		will have mail in /var/spool/mail/USER then you will
		need to make this partition as large as you think is
		needed
/usr		this is where most of the user applications will be
		stored; make this partition at least 1 GB in size
/tmp		temporary files... figure 256 MB to 2 GB is enough
swap		some say this should be double the amount of RAM you
		have installed, not necessarily true; a safe choice
		would be 256 MB to 512 MB, 1 GB if you're paranoid :)

You may also want to additional partitions, such as /backup for temporary
backup storage (you'll of course want to use CDs, DVDs or tapes for more
permanent solutions), or /ftp or /www for net-accessible file storage.
It is not recommended to mount the /home partition via NFS from a local file
server because you are counting on a single server, and if that fails, all
of your data is at a high risk. If you must NFS-mount your home directories,
make sure the NFS server has some type of RAID disk mirroring.

Post-Install Tasks
==================

After you have installed your distribution of choice, it is highly recommended
that you upgrade the kernel and add some security patches, as most basic
installations do not include these.

If you installed a 2.2.x system, you should take a look at the Openwall patches
to the 2.2 kernel series at http://www.openwall.com/linux/.

If you installed a 2.4.x system, grsecurity is probably your best bet, as it
incorporates most of the Openwall patches with some of its own and is a good
choice for shell servers, available at http://www.grsecurity.net/.

Begin by downloading the latest stable Linux kernel from the Linux kernel web
site at http://www.kernel.org/.

First, unpack the Linux kernel.

tar zxvf linux-2.4.18.tar.gz

Then apply the grsecurity patch.

cd linux
patch -p1 < ../grsecurity-1.9.5-2.4.18.patch

Start the kernel configuration process by first cleaning the source tree, and
then by starting the menu-based configuration utility.

make mrproper
make menuconfig

Kernel configuration is pretty straight-forward if you've done it before. Take
a look at the Linux Kernel HOWTO for more information and assistance. Be sure
to enable quotas, and build your network card's driver into the kernel so that
it will be a tiny bit faster! Also, a journaling file system such as reiserfs
is a good choice in case of crashes.

Once you have configured the kernel, compile the dependencies, modules, and
install them.

make dep
make bzImage
make modules
make modules_install

At the end of the "make bzImage" step, you should have a kernel image in
arch/i386/boot/bzImage if all goes well. Copy that to /boot with a new name
like /boot/linux-2.4.18-grsecurity and edit your boot loader's configuration
file (in this case LILO).

vi /etc/lilo.conf

Add these lines.

image = /boot/linux-2.4.18-grsecurity
  root = /dev/hda1
  label = linux
  read-only

Please change this accordingly and then run lilo.

lilo

It is a good idea to keep your old kernel file around in case anything goes
wrong, where you cannot boot the system. Reboot the system and see if your
newly-compiled kernel boots!


Installing Software
===================

Once your new security-enhanced kernel is up and running, be sure to create
some users and test out the new features.

Before following instructions for installing these software packages, be sure
to remove them from your system with the appropriate uninstall command. Refer
to your distribution's help files on how to do this.

First of all, edit /etc/skel to suit your needs.

cd /etc/skel
mkdir www
ln -s www public_html
mkdir ftp
ln -s ftp public_ftp

You should also place a .bash_profile startup file there with common aliases
for your users.

Sample /etc/skel/.bash_profile file:
####################################
# .bash_profile created by your shell provider
alias cls='clear'
alias l='ls -alF --color | more'
alias dir='ls -l'
alias cp='cp -i'
alias mv='mv -i'
alias rm='rm -i'
####################################

You may also want to add additional files into /etc/skel such as a default
web page in the /etc/skel/www/index.html file:
##############################################
<html>
<head><title>Under Construction</title></head>
<body>
<h2>This customer has not set up their web site,
please check back in a while.</h2>
</body>
</html>
##############################################

Once the skeletal configuration has been completed, you'll want to edit the
resource limits that PAM provides. First, let's take a look at the PAM limits
file in /etc/security/limits.conf. Please read the instructions in the
beginning of the file on what each field means. Below is a sample limits
configuration.

# all users have these limits
*          hard    nproc           30
*          hard    core            0
*          soft    nofile          50
*          hard    nofile          75
*          soft    stack           16384
*          hard    stack           16384
*          soft    data            32768
*          hard    data            65536
*          soft    memlock         16384
*          hard    memlock         32768
*          soft    rss             8192
*          hard    rss             16384
*          soft    as              262144
*          hard    as              393216
*          soft    fsize           262144
*          hard    fsize           393216
*          -       priority        5
*          -       maxlogins       3
# override the above limits for admins in the "staff" group
@staff     hard    nproc           70
@staff     -       maxlogins       5
@staff     -       priority        0

Please note that the maximum number of processes (nproc) MUST be above 20, or
programs like bash will not even start! It is recommended that this number
set higher for admins. Also, consider increasing the maximum file size for
admin users, as sometimes you may find yourself working with enormous file
sizes.

Package: Apache 1.3.26
Website: http://httpd.apache.org/

If you want SSL support in Apache, be sure to install the OpenSSL libraries
for cryptography support.

Two common SSL methods are out there: Apache-SSL and mod_ssl. Apache-SSL is
a set of patches that you apply to the source tree. mod_ssl is an actual
module that you compile in with the server. Apache-SSL is said to be less
bloated with features and more concerned with stability and security.

My personal choice is Apache-SSL, you may do as you like.

tar zxvf apache_1.3.26.tar.gz
cd apache_1.3.26
tar zxvf ../apache_1.3.26+ssl_1.48.tar.gz -C .
./FixPatch

Say 'y' when asked to fix the paths in the source. If all goes well, you are
now ready to proceed with the normal Apache configuration.

Now is a good time to decide what modules you want to include in your server.
The more modules you include, the bulkier the server will be, and the slower
your server will run. For a shell server, it is recommended that you do NOT
compile mod_perl or mod_php as modules because they will run scripts as the
webserver user 'nobody' and not under each user's own identity. Therefore,
it is recommended that you enable suEXEC (Server User EXECution), which will
execute all CGIs under the owner's identity. This means that Perl, PHP, etc.
will need to be CGIs and this will have a performance impact on the server
as a whole. Here is where a tradeoff must be made between speed and security.

Get the quick help on the default Apache configuration.

./configure --help

Please disable any modules that you do not plan on using. The following
is a good choice:

./configure --prefix=/usr/local/apache --disable-module=status \
 --disable-module=imap --disable-module=asis --enable-suexec \
 --suexec-caller=nobody --suexec-docroot=/home/httpd/html \
 --suexec-userdir=www --htdocsdir=/home/httpd/html \
 --server-uid=nobody --server-gid=nobody

You may want to enable other modules, note that Apache-SSL is enabled by
default. suEXEC is enabled above, with only the web server user 'nobody'
allowed to execute it, the root path where requests for suEXECable
scripts are allowed to run is /home/httpd/html (that will also be our
DocumentRoot as specified by the --htdocsdir opton), and instead of
having public_html as the user's web subdirectory, I like 'www' more, as
it is shorter and easier to remember! :-)

Compile and install the beast!

make
make install

While reading the Apache-SSL docs, edit your httpsd.conf file. I recommend
creating a virtualhosts.conf file and including that in your main server
configuration file, by adding "Include virtualhosts.conf" at the end.
This will make it easier for adding/removing/editing VirtualHost containers.

Next up, the FTP server.

Package: Pure-FTPd
Website: http://www.pureftpd.org/

If you don't like Pure-FTPd, then stick with ProFTPD!

./configure --with-sysquotas --with-throttling --with-ftpwho \
 --with-virtualhosts --with-diraliases
make
make install

Please read the docs for Pure-FTPd on how to run the server, as it has no
configuration file. The following command should start up a test copy,
however, do NOT use it on a production machine without reading the docs.

/usr/local/sbin/pure-ftpd -B -S XXX.XXX.XXX.XXX,21 -c MAX_USERS \
 -A -C MAX_CONN_PER_IP -i -k 95% -O stats:/var/log/pureftpd.log \
 -p START_PASV:END_PASV -P XXX.XXX.XXX.XXX -s -u 100 -T MAX_KB_PER_SECOND \
 -t MAX_ANON_KB_PER_SECOND

To host Virtual FTP sites, and assuming you have IP aliasing already figured
out. Be sure to give your normal users priority over bandwidth because they
are the ones paying for the account, and they will more likely respect the
rules, rather than anonymous users. Also, it is recommended that you set a
start and ending passive (PASV) mode port range, and open up those in your
firewall.

mkdir /etc/pure-ftpd
ln -s /home/USER/ftp /etc/pure-ftpd/XXX.XXX.YYY.ZZZ

It is recommended that you create some kind of script that will automatically
create these directories when a new domain user is added to the system, if
you plan to offer such service. This can only be accomplished if you allow
the ftp server to bind to all interfaces (0.0.0.0).

To allow anonymous users to upload files for each customer, you must make their
/home/USER/ftp/incoming directory with permissions 1777, but be careful of
accidentally creating warez sites! The -i option must be removed to allow
anonymous users to upload files.

If you are planning to run a SQL server you must install it before installing
PHP, as PHP needs the MySQL libraries to be able to compile correctly.

It is recommended that you run the latest stable version of the MySQL server.
Usually, if you have a recent (and decent :) Linux distribution, the version
that is included, should suffice, although installing it yourself will make
you more familiar with its directory structure and layout.

Package: DNS server
Website: Hmm... depends!

Choosing a DNS server depends on the DNS administrator's experience. If that
person, whoever it might be, is familiar with good 'ole BIND, then stick with
that. As we all know, BIND is infamous for its security vulnerabilities.

A security-minded person who is familiar with Dan Bernstein's software (most
notably, qmail) would probably be interested in his djbdns DNS server daemon.

There are several other excellent DNS servers out there that you may want to
explore. Whichever server you choose, make sure it is actively developed and
that security and stability are important goals of the project.

Package: MySQL server and client
Website: http://www.mysql.com/

Follow through these steps.

groupadd mysql
useradd -g mysql mysql
tar zxvf mysql-3.23.51-pc-linux-gnu-i686.tar.gz -C /usr/local
cd /usr/local
ln -s mysql-3.23.51-pc-linux-gnu-i686 mysql
cd mysql
scripts/mysql_install_db
chown -R root:root /usr/local/mysql-3.23.51-pc-linux-gnu-i686
chown -R root  /usr/local/mysql
chown -R mysql /usr/local/mysql/data
chgrp -R mysql /usr/local/mysql
chown -R root /usr/local/mysql/bin

Finally, start the server!

bin/safe_mysqld --user=mysql &

Press enter a few times and it should be gracefully running! If the daemon
dies, then look at the logs in the data directory.

Create the root user.

bin/mysqladmin -u root -p password 'new-password'
bin/mysqladmin -u root -h HOSTNAME -p password 'new-password'

It is not a good idea to keep your MySQL databases on the /usr partition,
so you may wish to symlink the /usr/local/mysql/data directory to a
partition that has enough space to hold all of your databases.

If you also want to install PostreSQL, then refer to some other docs!

Perl is usually installed on standard distributions, and does not need to
be recompiled. PHP however, is usually not installed correctly, or if it is,
it has not been optimally compiled to suit your needs.

Package: PHP
Website: http://www.php.net/

tar jxvf php-4.2.1.tar.bz2
cd php-4.2.1
./configure --enable-force-cgi-redirect --with-mysql --enable-discard-path \
 --with-openssl --enable-ftp --enable-memory-limit --enable-sockets \
 --enable-safe-mode --with-zlib --with-curl --with-xml \
 --enable-xslt --with-xslt-sablot
make
make install

If you want XSLT support: http://www.php.net/manual/en/ref.xslt.php

You may now edit /usr/local/lib/php.ini to suit your site's needs. You may
need to copy the sample php.ini file there if it does not exist. It is highly
recommended that you copy the sample if you are upgrading from an older
version of PHP.

Package: Webmin
Website: http://www.webmin.com/

Webmin is a great piece of software that can be used to remotely administer
your machine. It's a great way to have quasi-shell access tools if your SSH
server goes down.

You need the Perl SSLeay package installed if you want to access Webmin via
SSL, which is recommended, alternatively, you can use stunnel to tunnel the
connection via SSL. Install it before installing Webmin.

tar zxvf webmin-0.990.tar.gz -C /usr/local
cd /usr/local
mv webmin-0.990 webmin
cd webmin
./setup.sh

It is a good idea to start Webmin when your system boots, so if something
hangs the boot scripts, you can still login via Webmin and kill the offending
process... that is, if you don't have local console access or can't drive to
the NOC at 4 AM in the morning!


User Services Configuration
===========================

This section will provide information on how to configure the Apache web server
for actual user, the IMAP and POP3 servers, and the webmail software.


Administrative Scripts
======================

Here we go with the goodies!!! These little scripts will help you in your
daily tasks, such as adding, deleting, and modifying user information. If you
have any additions or corrections, please feel free to email them to me, and
I may include the them. 


TODO
====

* Finish writing it! :)
** bandwidth examples (monitoring, limiting, etc.)
* More generic examples? kill the version numbers ;)
* sample admin scripts
* convert to DocBook XML format


Resources
=========

http://www.tldp.org/ - The Liunx Documentation Project's website.

http://freshmeat.net/ - your first place to search for great linux apps

http://amir142.ods.org/shell-funcs.php - useful php functions


Conclusion
==========

I hope you learned a lot from this document, and please send any corrections,
suggestions, etc. to  and thanks for reading!

(C) 2002 Amir Malik.