The initial configuration of a box is done in a way that the user can
add information like domain names, reboot and things are up and
running. Instant success. That configuration mechanism, though it
covers a number of common cases, has its limits, of course. It gets
a new user going, but for special demands hand-crafting is called for.
These config files reside under '/box/cfg':
2 -rw-r--r-- 1 root wheel 2 Mar 14 11:34 diskspace
0 -rw-r--r-- 1 root wheel 0 Mar 14 11:57 domains
2 -rw-r--r-- 1 root wheel 24 Mar 16 14:47 hostname
0 -rw-r--r-- 1 root wheel 0 Mar 14 20:10 invoiceto
2 -rw-r--r-- 1 root wheel 14 Mar 16 14:47 ipaddress
2 -rw-r--r-- 1 root wheel 5 Jun 23 11:12 lowspace
2 -rw-r--r-- 1 root wheel 5 Jun 23 11:10 lowspaceto
2 -rw-r--r-- 1 root wheel 2 Feb 23 21:27 netspeed
2 -rw-r--r-- 1 root wheel 2 Mar 29 23:29 peakboost
2 -rw------- 1 root wheel 14 Mar 16 14:47 radaddress
2 -rw------- 1 root wheel 11 Mar 16 14:47 radsecret
2 -rw-r--r-- 1 root wheel 30 Apr 7 01:31 revname
0 -rw-r--r-- 1 root wheel 0 Mar 6 21:49 webname
And this is what they mean:
- ipaddress
- radaddress
- radsecret
-
Generated by the base system each time the box boots. So it is useless
to change these (you actually cannot).
- hostname
-
Initial hostname generated by the base system. You can alter it,
but you cannot remove or rename this file.
- domains
-
Empty at first, so the box's hostname is derived solely
from 'hostname'. Put the domain names you want to use for
the box into 'domains', one domain per line. The first line
automatically becomes the main domain name of the box, in places
where only one domain name can be given. So order is important here.
- webname
-
Related to 'domains' in that it can hold a single
additional domain name, that for the web server. While other services
should identify and know themselves under the main domain name
('mydomain.tld'), the web server as a special case can use something
like 'www.mydomain.tld'. This name is automatically propagated to
resouces that need to know about it as well, for instance the mailer
daemon and '/etc/hosts'. So there is no need to put 'www.mydomain.tld'
into 'domains' too.
- revname
-
If it exists, it should contain the reverse DNS name corresponding to the
IP address of the box, obtained by a DNS lookup. Setting up this file can
sometimes be necessary if the MTA (Exim) runs into problems with overly
paranoid (read: broken) remote MTAs that insist on the HELO/EHLO name
having to be identical with the IP address' reverse DNS name. Note that
the scope of this setting is local to the box. It does not "automagically"
alter the DNS mapping currently in place.
- invoiceto
-
If not empty, contains email addresses (comma separated)
you would like the monthly invoices to be sent to. For instance, you
could enter the email address of the accounts department here in order
to forward the invoice directly to where it belongs.
- diskspace
-
Usually contains '0', which means that the disk size should
remain as it is. Put an integer value between 200 and 2000 (requested
new disk space in Mbytes) into it and reboot. After some time the box
is up again, with the new disk size if all went well. If not, for
instance because the base system detected that your data probably
does not fit into the new disk, it reverts to the previous size. Nothing
gets lost. Note, however, that for each successful resize operation we
may charge you a small amount of money, depending on the billing plan,
since resizing a disk puts quite a burden on the system.
You can ping the box from the remote to monitor when it is finished
with resizing. Look into '/var/log/console' for any error messages.
You may want to make this a habit with every reboot since you do not
have any physical console to watch the booting. After successful
resizing 'diskspace' contains a '0' again.
- lowspace
-
If not empty, contains a single line comprised of two integer values
(in MBytes, whitespace separated) that override the low disk space
threshold defaults for '/' (1st value) and '/tmp' (2nd value). Note
however that if the new threshold is lower than the respective default
the notification mechanism will silently fall back to the default value.
For more details please see file 'lowspaceto'.
- lowspaceto
-
If not empty, contains email addresses (comma separated) you
would like low disk space notifications to be sent to, preferably
including a pager for swift human intervention. Notifications will be sent
hourly as long as there is (by default) less than 30 MBytes left on '/',
or 10 MBytes on '/tmp'. These limits constitute the minimum free disk
space necessary to run a server box in a safe and reliable way.
This mechanism is mainly intended to monitor disk space over longer
periods of time, to prevent situations where nobody might notice that
the server box slowly runs out of disk space. In case of a sudden
shortage, however, all bets are off. Even the notification itself
might fail due to insufficient disk space. Since this happens most
of the time when working online, you may want to watch out for error
messages indicating an out-of-disk-space condition.
- netspeed
-
Contains a single digit of '1', '2' or '3'. It determines your network
speed class, that is, whether the minimum network bandwidth per direction
(in and out) reserved for your box is 512, 1024 or 2048 kbit/s.
Note that the netspeed class can have an influence on the monthly fee
charged for resource usage, depending on the billing plan.
- peakboost
-
If it exists, contains a single integer value between 0 and 10 that
determines the responsiveness of your server box in peak load situations.
10 means best performance. The default and fallback value in case of a
configuration error is 10. Note that the peakboost level can have an
influence on the monthly fee charged for resource usage, depending on the
billing plan.
With all these config files it is important that you do not
accidentally leave empty lines, including trailing newlines, in them. Also,
trying to comment out lines with a hash mark ('#') or similar will not work.
The text parser in the various template files takes things pretty much
literally. So please watch your typing.
After you have edited these config files, but
before you reboot for the system to learn about the new setup, it is a
good idea to also configure the 'localtime' file, which sets the timezone
you would like your server to live in ('GMT' by default). Go to
'/usr/share/zoneinfo', select an appropriate file ('MET' for central
Europe, for instance) and symlink '/etc/localtime' to it. For instance:
ln -sf /usr/share/zoneinfo/MET /etc/localtime
Alternatively, you could use the program
'tzsetup'. Answer the first question about the machine's CMOS clock with
"Yes" and select the appropriate country in the full-screen menu.
When you then run 'date' you can see the effect
immediately. The daemon processes, on the other hand, still need a
reboot. So type 'reboot' now. 'reboot' in this context does all the
right things like running the shutdown scripts of the various daemons.
|
|
|
During reboot all files ending in '.eperl' under '/box/bin' get
executed. These files are config file templates that get piped
through a text preprocessor which executes the script commands (perl5)
embedded in the templates. The result are config files (installed
under '/box/etc') that have domain names, IP addresses etc. installed in
all the relevant places.
To make this work with the various system services symlinks are
installed in the appropriate locations, pointing to the relevant file
under '/box/etc'. So to change a configuration file you can do one of
two things: Either change the template under '/box/bin' and run
'/box/bin/configbox', or remove the symlink and install your own
config file. Note that in the latter case you will lose the box's
auto-configuration capability.
An alternative would be to copy the template file unter '/box/bin' to
some other name, ending in '.eperl', and edit that (hint: watch the
file permissions!). Since all templates ending in '.eperl'
automatically have their output installed under '/box/etc', all you need
to do then is change the symlink to point to your own file under
'/box/etc'. Note that you can also make use of that mechanism for
additional software you install.
At this point we would like to stress that, before you start editing
a configuration file of one of the preinstalled software, it is
certainly a good idea to find out whether this a genuine file or
a symlink to an automatically generated file under '/box/etc'. If
the latter, you need to edit the corresponding template file under
'/box/bin' (see above), or else you will be very disappointed after
the next reboot ...
|
|
|
During the initial boot the box generates its unique SSL and SSH
keys and (self-signed) certificates (SSH under '/usr/local/etc', SSL
under '/etc/ssl'). Each service using SSL gets its own copy of the key
and cert, accessible only by the user running the respective service.
Here is an example:
2 -r-------- 1 accel wheel 1314 Mar 14 09:58 accel.crt
2 -r-------- 1 accel wheel 891 Mar 14 09:58 accel.key
2 -r-------- 1 cyrus wheel 1314 Mar 14 09:58 cyrus.crt
2 -r-------- 1 cyrus wheel 891 Mar 14 09:58 cyrus.key
2 -r-------- 1 mailnull wheel 1314 Mar 14 09:58 mailnull.crt
2 -r-------- 1 mailnull wheel 891 Mar 14 09:58 mailnull.key
2 -r-------- 1 news wheel 1314 Mar 14 09:58 news.crt
2 -r-------- 1 news wheel 891 Mar 14 09:58 news.key
2 -r-------- 1 root wheel 1314 Mar 14 09:58 server.crt
2 -r-------- 1 root wheel 891 Mar 14 09:58 server.key
4 -r-------- 1 root wheel 2205 Mar 14 09:58 stunnel.pem
With this setup, you can replace the SSL key/cert for one service and
leave the others alone. One common case is an officially signed cert
for a web server that is usually branded with 'www.mydomain.tld', while
the certs for the rest of the services should continue to match
'mydomain.tld'. Note that the key/cert for the web service is contained
in 'accel.*' since for efficiency we do SSL encryption in the
accelerator in front of the actual web server. If you replace
keys/certs try not to break the file permissions, which otherwise
could result in a security problem if someone unauthorized gets hold
of these files.
To generate your own SSL keys and (self-signed) certificates, there
is a program 'mksslcrt' under '/box/bin'. Apart from some other
information, at one point it asks you for the 'common name'. This is
where you are expected to give the domain name for which you want to
use the cert. The new key/cert pair gets installed as 'new.key' and
'new.crt' unter '/etc/ssl'. You can then copy the files into an
existing key/cert pair (watch the file permissions!). Note that you
need to reboot your box afterwards for the relevant daemons to learn
about the change.
Similarly, to generate a CSR you can send to a certification company
for an official signature you can use 'mksslcsr'. It generates
'new.csr' under '/etc/ssl', along with 'new.key'. Make a backup copy of
'new.key' to some safe location. It you lose that file the expensive
official certificate is worthless! The company, on receipt of the CSR
and after checking your identity, eventually sends you back a CRT file
which you would save as 'new.crt'. From there it is the same as for
self-signed certs (described above). For instance, if you need the
cert for your web service under domain 'www.mydomain.tld', copy both
'new.key' and the officially signed 'new.crt' into 'accel.key' and
'accel.crt' and reboot. That's it.
Hint: When the certification company asks you about the
web server you want to use the certificate with, tell them
'Apache+mod_ssl'. While we actually do not use 'mod_ssl', the
certificate our setup works with is of the same type 'mod_ssl'
requires. Note also that our preinstalled server software supports
certificate chains, that is, certificates that require one or more
intermediate certificates to be installed along with them. Just put
them all in the respective '.crt' or '.pem' file, in reverse
chaining/signing order (your domain certificate first, then the
intermediate certificates up to the root certificate).
|
|
|
As you would expect from a UNIX system, the basic config files reside
under '/etc'. On the other hand, add-on packages, that is, those that
show up when you type 'pkg_info', like to put their config files under
'/usr/local/etc'.
Many of the daemons providing the preinstalled services
are add-on packages and therefore have their start and stop scripts
(which contain commands executed at boot and shutdown time, respectively)
under '/usr/local/etc/rc.d'.
Here is how it looks by default:
2 -r-xr-xr-x 1 root wheel 367 Mar 2 11:53 .100.mysql-server.sh*
2 -r-xr-xr-x 1 root wheel 1123 Oct 10 13:21 .110.pgsql.sh*
2 -r-xr-xr-x 1 root wheel 501 Sep 30 20:10 .220.spamd.sh*
2 -r-xr-xr-x 1 root wheel 544 Jan 28 14:46 .260.exim-2.sh*
2 -r-xr-xr-x 1 root wheel 1106 Jun 10 10:32 .300.jakarta-tomcat3.sh*
2 -r-xr-xr-x 1 root wheel 1129 Mar 23 12:55 .300.jakarta-tomcat41.sh*
2 -r-xr-xr-x 1 root wheel 1129 Oct 1 18:38 .300.jakarta-tomcat50.sh*
2 -r-xr-xr-x 1 root wheel 181 Mar 1 13:33 000.mysql-client.sh*
2 -r-xr-xr-x 1 root wheel 211 Nov 9 14:37 000.named-seed.sh*
2 -r-xr-xr-x 1 root wheel 248 Feb 14 00:05 000.pkgtools.sh*
2 -r-xr-xr-x 1 root wheel 393 Mar 27 14:38 010.sshd.sh*
2 -r-xr-xr-x 1 root wheel 320 Jun 10 16:50 200.radiusd.sh*
2 -r-xr-xr-x 1 root wheel 230 Feb 24 22:12 220.saslauthd.sh
2 -r-xr-xr-x 1 root wheel 523 Mar 3 10:21 230.imapd.sh*
2 -r-xr-xr-x 1 root wheel 534 Jun 19 09:54 250.exim.sh*
2 -r-xr-xr-x 1 root wheel 323 Mar 21 16:37 320.apache.sh*
2 -r-xr-xr-x 1 root wheel 460 Mar 3 10:15 350.accel.sh*
2 -r-xr-xr-x 1 root wheel 218 Mar 21 16:40 370.htdig.sh*
2 -r-xr-xr-x 1 root wheel 398 Mar 12 11:09 400.innd.sh*
2 -r-xr-xr-x 1 root wheel 439 Mar 7 20:00 900.stunnel.sh*
It works like this: The prefix number determins the order in which
these files get executed on boot. On shutdown, the reverse order is
applied so that you get kind of a nesting effect, which is what you
would expect. Files with a leading dot ('.') are suspened, that is,
they are still there but will not get executed. If you want to disable
one of the daemons the proper way is to put a dot in front of the
respective script file's name by renaming it. Note however that
you might have to take care of other places as well, like crontabs,
'/etc/newsyslog.conf' etc.
Some of the services are disabled by default because not everybody needs
them. The MySQL database, for example. So their start/stop scripts
have that dot in front of their name. If you want to enable them, just
remove the dot and reboot your box. They should start up automatically.
Note that in case of jakarta-tomcat (Java servlets/JSP) you also need
to uncomment the 'Include' line dealing with 'mod_jk' in Apache's config
file, or rather its template file '/box/bin/httpd.conf.eperl'.
When it comes to monitoring the various services, most have their
log files under '/var/log', and their temporary data like PID files
under '/var/run'. So if you wonder why something does not work as
expected there is a good chance that you can find the answer in one
of these places.
And finally, where most of what you do will probably take place is
'/home' and '/www'. The former contains the home directories of
normal (unprivileged) users, the latter the directories where
your web presence lives. Document root is '/www/data', while
Apache's icons are in '/www/icons', CGI programs in '/www/cgi-bin' etc.
|
|
|
In contrast to FreeBSD's standard "jail" mechanism,
for a maximum of compatibility our enhanced implementation fully supports
features like SysV IPC (for PostgreSQL etc.), raw IP sockets (ping,
traceroute etc.), per box filesystem quotas and more.
However, in order to protect the privacy and data
integrity of each individual server box there are limits to what we can
allow processes running in this environment to do. The line is drawn
where a process might be able to access global information in the base
machine's RAM or filesystems, and could therefore get hold of confidential
data belonging to others. The system prevents such trespassing.
This means that some of the more intrusive system
administration commands will not work, or only partially. On the other
hand, monitoring and debugging programs like 'netstat', 'truss', 'df',
'top', 'ipcs' etc. all work as expected. Since users in a managed
environment typically do not need to deal with system administration
and do not have direct access to the hardware in any case, minor
limitations in this area are probably tolerable.
Creating device nodes ('mknod') falls into this
category. For security reasons we cannot allow this within the server boxes,
or else users would have arbitrary access to device drivers that directly
control hardware components, like hard disk controllers etc. All other
file types work as expected, though. Having to create additional device
nodes happens rarely. If you need some for a 'chroot' environment, for
instance, please contact our support and we will create them for you.
Unlike "normal" FreeBSD systems, where you can optionally install a Linux
emulator, our server boxes come without Linux support. This is for technical
reasons. The mechanisms we had to employ to make our system work in its
unique way are not compatible with the Linux emulator, and there are
also security concerns in an environment like ours. Linux emulation
under FreeBSD is usually important only in the desktop area where you
would like to run Mozilla, Adobe Acrobat Reader, StarOffice and so on. Server
oriented applications, on the other hand, are almost always available as
native FreeBSD ports and packages, which means that for things you normally do
with an Internet server, binary Linux compatibility is likely to be not
an issue.
We run several of our supporting sites, including
our company web and email server, in these boxes, too, without any
compatibility problems, which might serve as an indicator that those few
peculiarities of our system are of little relevance when it comes to
day-by-day usage.
|
|
|
|
