Server Setup with Debian GNU/Linux 3.1 'Sarge'

Contents

Introduction
Foundation
Minimum Features
Miscellaneous Main Features
File Serving Etcetera
Network Services
Troubleshooting

Introduction

See my related documents on setting up a desktop system using Debian which includes some aspects common to both servers and desktops: Desktop System Setup with Debian Sarge; Desktop System Setup with Debian Testing/Etch.

I also provide a menu driven command-line program, called Twix, to help you install most of what is covered in this document and configure some of it. Twix can be downloaded for free from http://thegoldenear.org/toolbox/unices/twix/.

Notable changes to this document

0.7.24 - 22 January 2009 - package repositories changed - the main Debian archive no longer includes Sarge packages and Sarge security updates, so ftp.uk.debian.org and security.debian.org have been replaced with archive.debian.org

0.7.20 - 5 March 2008 - Added 'Network Addressing' section to 'General Configuration' section; improved 'updates' section in 'Linux kernel updates'.

0.7.19 - added 'updates' section to 'Linux kernel updates' section with examples of the different messages you're likley to see when updating.

0.7.15 - 10 December 2007 - Squirrelmail - added configuration to make use of IMAP SORT

0.7.14 - November 2007 - Added 'set no bouncemail' to Fetchmail configuration to fix issue of replying to spam email

Glossary

<something> - when something is in angle brackets you should replace this with something particular to your system; you do not use the angle brackets.

command - text in monospaced typeface indicates a command you issue at the command-line or text you type yourself into a text editor.

$ - when a command-line command is preceded by a dollar it means you run this whilst logged in as a regular user

# - when a command-line command is preceded by a dollar it means you run this whilst logged in as super user / root

Package repositories

There are different providors of Internet server sources

Debian installs with a default that uses 'main', it doesn't include 'contrib' or 'non-free'.

General configuration

Use the latest Debian 'stable' distribution (this document is for version 3.1) from http://www.debian.org/distrib/

Set the time to GMT in the BIOS before installing Debian. During installation, say that the system clock is set to GMT. Debian will take care of setting your localised time correctly (as an offset from GMT).

Partitioning Scheme

Debian Installer's 'Multi-user workstation' option will create the following kind of partitions:

You may want to locate /home on a separate disk.

You may want to manually partition like so:

Partition No. Partition type Size Mount point File system Usage
1 primary 300MB / ext3
5 logical min 2GB? 5GB - 7GB if use WPKG /usr ext3
6 logical 3GB /var ext3
7 logical 1GB max swap swap
8 logical 500MB /tmp ext3
9 logical whatever is appropriate /home ext3 User home directories

Network Addressing

Add to /etc/network/interfaces this kind of addressing information (your scheme may need to differ):

auto eth0
iface eth0 inet static
	address 10.0.0.10
	netmask 255.255.255.0
	gateway 10.0.0.1
	dns-nameservers 10.0.0.1
	dns-search localdomain

Miscellaneous

Don't install applications using Tasksel or DSelect, just install the basic system and manually install any software we specifically require or use Twix.

Download and apply any security updates using 'aptitude update' then 'aptitude dist-upgrade'

Install any diagnostic programs for network card(s)

Make a rescue/boot floppy disk: mkboot

Useful Tools

Mail Transfer

If you want the system to be able to send out mail, such as for sending logs to you, and you don't have a full-blown mail server:

Backup - Backup Manager

Package(s)

Getting a newer version from Debian Backports

The version of backup-manager in Debian Sarge is 0.5.7. Newer versions of backup-manager write to a wider array of media, such as DVD rewritables. You can get a newer version of backup-manager from backports.org. Here's a reference of one of backup-manager's authors recommending doing just this. This is how you do it:

Configuration

Configuration file: /etc/backup-manager.conf.

Schedule configuration file: /etc/cron.d/backup-manager.

A debconf priority of 'low' is advised if you want to be asked if the backup is to be written to CD/DVD or to another computer using SSH.

The backup is automatically scheduled with cron to run at 04:00.

The easiest and officially recommended method to configure backup-manager is using dpkg-reconfigure backup-manager. Alternatively you can edit its configuration file.

If you are trying to write the backup to CD using an ATA CD writer and its failing, follow this from the Backup Manager User Guide (the man page with version 0.6.2 doesn't explain this option anywhere near as well):
"Backup Manager uses cdrecord for burning CDs. If when you run cdrecord -scanbus you don't see your burning device, that means you will have to force the device in ATA mode. To tell Backup Manager to do so, just put here the path to your device, and a switch will be appended to the cdrecord commandline like the following : cdrecrord ... dev=$BM_BURNING_DEVFORCED ....
Leave this configuration key blank if you see your device with cdrecord -scanbus, in this case, Backup Manager will use the default cdrecord device for burning CDR media.
Example: export BM_BURNING_DEVFORCED="/dev/cdrom""

Usage

You will generally leave responsibility with cron to schedule backups but you can run it manually with backup-manager -v.

Troubleshooting

The log of messages describing backup-manager's operations go to /var/log/messages with the tag backup-manager.

The log of what happened when writing to CD/DVD go to /tmp/bm-burning.log.<6 seemingly random characters>.

Further Information

/usr/share/doc/backup-manager

/usr/share/doc/backup-manager-doc

Backup Manager Documentation, including User Guide: http://www.backup-manager.org/documentation/.

An example configuration file: http://www.backup-manager.org/documentation/backup-manager.conf.html.

Backup - Flexbackup

Package(s)

Usage

Schedule using /etc/crontab:
00 1 * * 1-5 root flexbackup -set home -full

From the command-line

flexbackup -newtape flexbackup -set home -full

List files in archive: flexbackup -list

List current device's table of contents: flexbackup -toc

To quickly extract just a single file, use -extract -onefile path/to/my/file, giving the path from the archive.

To extract a list of multiple files, put them into a text file, for instance "restorelist", then use -extract -flist restorelist. The format is one line per pathname, using the path of the file in the archive.
Note if you are using afio with compression you need to append .z to filenames for any compressed files (depends on threshold and exclusion patterns).

Flexbackup logs to /var/log/flexbackup/ with filenames such as flexbackup.list.200705081249.log, home.0.200705100200.gz, home.latest.gz.

Configuration

Configuration file: /etc/flexbackup.conf (See http://www.edwinh.org/flexbackup/flexbackup.conf.txt)

It's possibly better to do '-full' backups because less complex when restoring files; works around using the '-level' option ('-full' defaults to '-level 0').

Backup - Tape Drives

Package(s)

Usage

You don't create a file system on a tape, nor do you mount it or attempt to access the data on it as files. You simply treat the tape device itself as a single 'file'.

SCSI tape drives are referenced by /dev/st0 (device is "rewind on close") or /dev/nst0 (device is "don't rewind on close".

Use tar to read and write files and directories to and from the tape, with the following options:

Use mt to control the tape drive, with the following syntax: mt -f /dev/st0 command where command would be any of the following:

Write files to a tape:
tar cvf /dev/st0 files-or-directories-to-backup
(by default it recurses into sub-directories)

Retrieve a complete archive back from a tape to the current working directory:
tar xvf /dev/st0
(be mindful of the directory you're in when you run this as it could overwrite files in your current directory)

List the files on a tape:
tar tvf /dev/st0

Retrieve individual files from a tape to the current directory:
tar xvf /dev/st0 filename1 filename2 filename3

You can schedule backups using cron, via the configuration file /etc/crontab, such as with this line which will run your own backup script at 04:00:
00 4 * * * root /root/backup.sh

Troubleshooting

Check that the operating system sees the device by running dmesg and looking for "attached SCSI tape st0 at".

List SCSI devices:
cat /proc/scsi/scsi.

See man pages on 'mt' and 'st'.

Apache - web server

Package(s)

If you instead need to use 'apache2', also install 'apache2-mpm-prefork' because "so long as you're using the prefork mpm. PHP isn't (yet) completely thread safe... it's a backend module for apache which behaves simillarly to apache 1. i.e. one child process per request."

Troubleshooting

Error log (this includes database connection errors from web applications such as egroupware): /var/log/apache/error.log

PHP - for programming databases

Package(s)

Compression / Archival

These can be useful for many reasons, for example the anti-virus and spam co-ordinating program Amavis uses many of them if they're installed.

Package(s)

mySQL - database server

Package(s)

Configuration

MySQL will only install if the system already has a non-numeric hostname that is resolvable via the /etc/hosts file. Run hostname -f; if it returns just the machine's name, i.e. 'server', rather than its fully qualified domain name (FQDN) - its name followed by its domain, i.e. server.localdomain or server.yourdomain.org - then you need to add a line to /etc/hosts with its IP address then FQDN then name such as '10.0.0.10 server.localdomain server'. For example:

127.0.0.1 localhost.localdomain localhost server
10.0.0.10 server.localdomain server

Set a password for the MySQL root user because it defaults to not having one. You can do so in a number of ways.

a) Set the password from the command-line:

b) Set the password from within MySQL:

a) Set the username and password in a my.cnf configuration file:

For security Debian's MySQL defaults to listening only on the localhost (127.0.0.1) network interface for connections, so it will not allow remote connections. This is achieved by setting bind-address 127.0.0.1 in /etc/my.cnf (The less secure skip-networking option used to be used instead for this). This is fine for a mail server running on the same machine or phpMyAdmin but not for OpenOffice clients connecting using ODBC for instance. You can enable only remote connections to MySQL by changing bind-address to the machine's IP address or hostname. You don't seem to be able to set it to both. You can enable connections from any source by removing bind-address.

The MySQL configuration file can live in a number of locations:

To reset the MySQL root password if you've lost it:

(From http://dev.mysql.com/doc/refman/5.0/en/resetting-permissions.html)

If you're wanting to use ODBC to connect client computers across a network to the database server, nothing has to be set on the server specifically to enable this ODBC connection.

Usage

The location of database files is usually /var/lib/mysql/your-database-name (use mysqladmin variables | grep datadir to find it otherwise)

To open the mysql program: mysql -u <username> -p. The -p tells it a password is required, which you will be prompted for.

To create a database:

To first delete the database if it already exists:
mysql> drop database <database>;

Set privileges on the database (grants the root account all database level access on your database when connecting from any machine, using the defined password and allows them to give other users priviliges. See http://dev.mysql.com/doc/refman/5.0/en/grant.html for reference):

See which users have privileges in MySQL:

See what databases have what users with privileges to access them:

list the privileges granted to the account that you are using to connect to the server:
mysql> show grants;

list the privileges granted to a specific account, for example:
mysql> show grants for 'root'@'localhost';

MySQL server (mysqld) administration, using the command-line - these are the main MySQL clients and processes:

Further Information

MySQL 3.23, 4.0, 4.1 Reference Manual: http://dev.mysql.com/doc/refman/4.1/en/

MySql 4.1.x Database Survival Guide: http://www.akadia.com/services/mysql_survival.html

'MySQL Database Administration' - 'MySQL User Account Management' - 'MySQL Usernames and Passwords'

RAID arrays

The host controller may itself provide RAID capability, in which case this hardware RAID will be superior to using Linux software RAID but only as long as the host controller is of high quality. Linux software RAID is usually superior to the cheap IDE (pseudo hardware), RAID controllers; and also superior to 'fakeraid' controllers such as Adaptec's 'HostRaid'. Note that host-based RAID controllers may support only a sub-set of the various RAID levels.

You may find when you configure a RAID array in your host's software at boot time that the Debian installer partitioning section still sees both disks independently. In this case you need a driver for the host controller that isn't available in Debian. For example Adaptec provide a binary-only HostRaid controller driver. just use Linux software RAID.

We use Software RAID 1 (mirroring). See 'Standard RAID levels': en.wikipedia.org/wiki/Standard_RAID_levels for a description).

Package(s)

Configuration

The multidisk device (or, after its most famous variant, 'software RAID'). New devices made up of combined traditional disk devices into RAID volumes referred to as /dev/md#. RAID is not a guarantee for data integrity, it just allows you to keep your data if a disk dies (that is, with RAID levels above or equal one, of course). This Software RAID is usually superior to the cheap IDE (pseudo hardware) RAID controllers found on newer motherboards but not as good as hardware RAID as on a dedicated SCSI or SATA RAID controller card.

Read this: http://www.tldp.org/HOWTO/Software-RAID-HOWTO.html#toc

The tool you use to work with RAID arrays is mdadm.

You can use the Debian Installer to setup a RAID array, rather than doing so manually:

You can run mdadm as a daemon by using the follow-monitor mode. If needed, that will make mdadm send email alerts to the system administrator when arrays encounter errors or fail. Also, follow mode can be used to trigger contingency commands if a disk fails, like giving a second chance to a failed disk by removing and reinserting it, so a non-fatal failure could be automatically solved. Let's see a basic example. Running mdadm --monitor --mail=root@localhost --delay=1800 /dev/md2

Is the MD driver compiled as a module or compiled into the kernel? compiled into the kernel.

Configuration files

? /etc/raid/raidtab, and a symlink from /etc/raidtab

/proc/mdstat

Usage

mdadm --query /dev/md0

mdadm --detail /dev/md0

Further Information

Recovering a RAID disk back into a RAID device /dev/md*: http://www.kieser.net/linux/raidhotadd.html

Installing Debian with SATA based RAID: http://wiki.xtronics.com/index.php/Raid

probly too out of date, but seemed useful: http://www.james.rcpt.to/programs/debian/raid1/

Samba - Windows file and print server

Package(s)

Creating a Primary Domain Controller

See our separate document Setting up a Samba primary domain controller and file/print/software deployment server using Samba 3 on Debian 3.1 Sarge.

Simple Samba File Sharing

Use this /etc/samba/smb.conf configuration file:

# Samba 3.0.x configuration file for simple password-less file sharing.

# (if we set security=no would this work with Windows 95, 98 and Me clients?)

[global]

# The server's name on the Windows network
netbios name = server

# The workgroup name. Make this the same on all participating computers
workgroup = workgroup

# Combined with 'guest account' this doesn't require a username/password 
# to connect
security = share

# Makes this the WINS server for the network.
# Required for computers to browse for the share
wins support = yes

# Defines which Unix account will be used when the share is used
guest account = nobody

# Try to make sure this machine is the local master browser so that what
# it says, goes, amongst it and the other computers on the (WINS) network
os level = 34
preferred master = yes


[shared]
guest only = yes

guest ok = yes

# The directory that will be shared
path = /home/samba/shared

# It is visible when people are browsing the network
browseable = yes

read only = no

# New files are created with this permission
# Requires a corresponding Unix setting
force create mode = 0666

# New directories are created with this permission
# Requires a corresponding Unix setting on the directory
force directory mode = 2770

Create the shared directory:
mkdir /home/samba && mkdir /home/samba/shared

Give it liberal permissions:
chmod 666 /home/samba/shared

Creating shares that can be mounted from a GNU/Linux workstation

This share can be mounted by root but files take the permission of whomever creates them.

This is what to do on the server, for what to do on the workstation see Desktop System Setup with Debian GNU/Linux 'Testing/Etch'. or Desktop System Setup with Debian GNU/Linux 3.1 'Sarge'.

Mail server

If you only want your system to be able to have the ability to send out mail, for example to email you logs, then see Mail Transfer.

We recommend Christoph Haas' 'Tutorial: ISP-style Email Service with Debian-Sarge and Postfix 2.1', at http://workaround.org/articles/ispmail-sarge/. This solution provides POP3/IMAP access and webmail access to multiple domains, virus scanning, spam prevention, secure mail relay access for road-warriors and easy domain administration. It accomplishes this using Postfix SMTP, MySQL database, Courier POP3/IMAP, Cyrus SASL, AMaViS spam and virus detection using SpamAssassin and ClamAV.

In addition to that tutorial, if your server isn't required to receive its own email directly and/or send it directly you can use Fetchmail to collect from a POP3 host (see the Fetchmail section of this document) and add a relay host to Postfix that will deliver mail on your behalf.

Our Debian system configuration script, Twix, version 0.2 onwards, can set this mail server up for you (but you should read the tutorial first).

Installation

Questions and recommended answers for package installation:

Configuration

This is additional configuration to what is described at workaround.org.

Postfix

To add a relay host to Postfix that will deliver mail on your behalf add relayhost = [<your ISP's SMTP server>] to /etc/postfix/main.cf.

Query Postfix's configuration:

AMaViS

To enable the list of attachment types that will be rejected uncomment /etc/amavis/amavisd.conf's $banned_filename_re section.

Squirrelmail

Add the Squirrelmail Apache configuration to Apache, enabling an address such as http://server/squirrelmail to load Squirrelmail:
ln -s /etc/squirrelmail/apache.conf /etc/apache/conf.d/squirrelmail.conf
(if you were using Apache 2 you'd instead use /etc/apache2/conf.d/squirrelmail.conf)

Configure that Squirrelmail Apache configuration, /etc/squirrelmail/apache.conf, to enable the specific address http://mail.server to load Squirrelmail (change the name if you call your server something else)

#When accessed from anywhere on port 80 at mail.server, respond with Squirrelmail:
#This also requires a DNS entry for mail.server
<VirtualHost *:80>
  DocumentRoot /usr/share/squirrelmail
  ServerName mail.server
</VirtualHost>

For mail.server to work you also need to register it with your DNS server:
Host IP address: 10.0.0.10
Hostname: mail
Domain name: server

Make use of IMAP SORT to improve performance when there's lots of email in a folder and fixes the issue with a large inbox where the server tries to download to you right_main.php rather than display the inbox (From 'Optimizing SquirrelMail - IMAP server extensions' - www.squirrelmail.org/docs/admin/admin-6.html#ss6.3).
Use either method:

Usage

You can use either PHPMyAdmin or the command-line for any of these. Here are the command-line methods.

Domains

Create a virtual domain (you'll be asked for the MySQL root user password):
mysql -u root -p -D provider --exec="INSERT INTO domains VALUES('<domain name>')"

Mailboxes

Create a user mailbox (you'll be asked for the MySQL root user password):
mysql -u root -p -D provider \
--exec="INSERT INTO users VALUES('<mailbox name>@<domain name>','<password>')"

Send a new user an email to initialise their mailbox:
echo -e "Welcome to your new email account.\r\nEverything should be working, let us know if it isn't." | mail -s "Welcome" <mail name>@<domain name>

Remove a user mailbox:
mysql -u root -p -D provider \
--exec="DELETE FROM users WHERE email = '<mailbox name>@<domain name>' LIMIT 1"

Forwardings

Forwardings, AKA aliases. They are actually redirections. Use them for redirecting to both local and remote addresses. To forward to multiple addresses, separate addresses with a comma. You'll be asked for the MySQL root user password.

These use the MySQL account 'root' but you might use a different account.

To list all existing forwardings:
mysql -u root -p -D provider --exec="SELECT * from forwardings"

To redirect mail for one mail address (which may or may not actually exist) to another mail address:
mysql -u root -p -D provider \
--exec="INSERT INTO forwardings (source, destination) VALUES \
('<mailbox 1>@<domain name>','<mailbox 2>@<domain name>')"

To redirect mail to another mail address and also leave a copy in the original mailbox:
mysql -u root -p -D provider \
--exec="INSERT INTO forwardings (source, destination) VALUES \
('<mailbox 1>@<domain name>','<mailbox 1>@<domain name>,<mailbox 2>@<domain name>')"

To send mail for all the addresses at your domain for which you don't have a mailbox to a single mailbox:
mysql -u root -p -D provider \
--exec="INSERT INTO forwardings (source, destination) VALUES \
('@<domain name>','<mailbox name>@<domain name>')"

To redirect a whole domain, use a forwarding of @my.domain to @another.domain:
mysql -u root -p -D provider \
--exec="INSERT INTO forwardings (source, destination) VALUES \
('@<domain name 1>','@<domain name 2>')"

For legal reasons you should forward email to postmaster and abuse to a specific mailbox where they will be read:
mysql -u root -p -D provider \
--exec="INSERT INTO forwardings (source, destination) VALUES \
('postmaster@<domain name>','<mailbox name>@<domain name>'), ('abuse@<domain name>','<mailbox name>@<domain name>')"

To change an existing forwarding source:
mysql -u root -p -D provider \
--exec="UPDATE forwardings SET source = '<new forwarding source email address>' WHERE source = '<forwarding source email address to change>' AND destination = '<matching forwarding destination email address>';"

To change an existing forwarding destination:
mysql -u root -p -D provider \
--exec="UPDATE forwardings SET destination = \
'<new forwarding destination email address>' WHERE source = '<forwarding source email address to change>' AND destination = '<matching forwarding destination email address>';"

To remove a forwarding, by its source address:
mysql -u root -p -D provider \
--exec="DELETE FROM forwardings \
WHERE source = '<forwarding source to remove>';"

Mail Queue

postqueue - Postfix queue control - for unprivileged queue operations such as listing or flushing the mail queue. For example postqueue -p or postqueue -pvvv.

postsuper - Postfix superintendent - for queue operations that require super-user privileges such as deleting a message from the queue or changing the status of a message. Use of the command is restricted to the superuser.

Delete a single message from the queue:
postsuper -d <queue ID>
(applies to hold, incoming, active and deferred queues)

Remove all messages from a particular queue:
postsuper -d ALL %lt;queue%gt;
(where queue can be hold, incoming, active or deferred)

Troubleshooting

Look at /var/log/syslog or /var/log/mail.log.

Show open ports and whether they listen on just localhost or for remote connections:
netstat -l -t -p
If you see tcp 0 0 127.0.0.1:3306 0.0.0.0:* LISTEN 29945/mysqld it means the server is only listening locally.

Check open ports:

Check 'master' is running.

Flush the queue - attempt to deliver all queued mail (warning: flushing undeliverable mail frequently will result in poor delivery performance of all other mail):
postqueue -f
This can similarly be achieved using:
postfix flush

List contents of the mail queue (add -v to be more verbose, add multiple -v's for increased verbosity):
mailq or postqueue -p

Schedule immediate delivery of all mail that is queued:
mailq -q

Schedule immediate delivery of all mail that is queued for the named site. This option accepts only site names that are eligible for the "fast flush" service, and is implemented by executing the postqueue(1) command. See flush(8) for more information about "fast flush":
mailq -qRsite

Logs

Mail in general: /var/log/mail.log

AMaViS: /var/log/amavis.log - lists its capabilities and mail it's dealt with

Clam: /var/log/clam/clam.log

Freshclam: /var/log/clam/freshclam.log

If you're sending email to the server to test it, whilst looking at a log file, it can be useful to email an address like xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@<domain> to make it easy to spot.

Note

Postfix defaults to not accepting mail larger than 10MB. This limit is for good reason so you probably don't want to increase it but if you do you override it with the message_size_limit parameter in /etc/postfix/main.cf

Further Information

Postfix

Man pages for Postfix daemon processes you'll see mentioned in syslog: cleanup, local, master, qmgr, smtp, smtpd, virtual.

You can learn a lot by reading through the archives of the postfix-users mailing list: http://www.postfix.org/lists.html

Mail retrieval using Fetchmail

Fetchmail retrieves mail from a remote mail server and sends it to your local SMTP server.

Package(s)

Configuration

Fetchmail runs in general mode or daemon (AKA service) mode, by default checking every 5 minutes. Its behaviour is controlled by command-line options and/or a run control (i.e. config) file, either a system-wide one (/etc/fetchmailrc) or in per-user home directories (~/.fetchmailrc). The fetchmail package installer doesn't create a config file for you, you either create it manually or use the fetchmailconf utility (seperately, on a workstation) to create and edit a .fetchmailrc in the home directory of the user that runs it; fetchmailconf requires X windows.

The normal mode of fetchmail is to try to download only 'new' messages, leaving untouched (and undeleted) messages you have already read directly on the server (or fetched with a previous fetchmail --keep).

The most thorough explanation of Fetchmail's configuration is in info fetchmail.

Set restrictive permissions on the fetchmail configuration file because it contains passwords:
chmod 0600 /etc/fetchmailrc
chown fetchmail /etc/fetchmailrc

Example /etc/fetchmailrc configuration file:

# Fetchmail configuration file
# /etc/fetchmailrc for system-wide daemon mode
# Version 1.3

# Changes:
# 1.3 - 13 Nov 2007 - added 'set no bouncemail'.
# Fetchmail's default is to bounce mail to addresses that don't exist. This is
# known as backscatter and in a world of spam you don't want to reply to either
# a spammer or the address they forged. With this set an error mail is sent to 
# postmaster rather than the sender, which for us goes nowhere.
# 1.2 - 18 Oct 2007 - added 'set postmaster ""' so unknown user emails are discarded; restored missing defaults protocol pop3
# 1.1 - Pete - 14 Aug 2007 - Added example using 'envelope 1 "Delivered-To:" qvirtual "109-"'

# How often to poll servers, in seconds. The default is 300.
set daemon     90

# Logging - don't log to syslog because so much is kept
set no syslog

# Logging - log to the specified log file
# (Beware that if you're using the log for troubleshooting, it can grow quickly)
# (The log file wants to be editable by the user fetchmail)
# (How do we cycle the log file? /etc/logrotate.conf?)
#set logfile /var/log/fetchmail


defaults
protocol pop3

set postmaster ""
# Set no postmaster so mail tagged as SMTP 550 error 'Recipient address
# rejected: User unknown in virtual mailbox table' is discarded rather
# than going in fetchmail's mailbox (/var/mail/fetchmail) and eating up
# disk space

set no bouncemail
# Fetchmail's default is to bounce mail to addresses that don't exist.
# This sets Fetchmail to instead send an error to postmaster.

# The verbose syntax is like this
# poll SERVERNAME protocol PROTOCOL
#	user USERNAME with password PASSWORD is LOCALUSERNAME here;

# Example of various user accounts on the same server
#
# poll pop.provider.net proto pop3
#	user \"jsmith\" with pass \"password\" is \"smith\" here
#	user jones with pass \"password\" is \"jjones\" here

# Example of a multi-drop mailbox
#
# poll pop.provider.net localdomains loonytoons.org toons.org:
#	user your_username with pass your_password to * here

# Example of a multi-drop mailbox where mail
# - host doesn't provide 'X-Envelope-To' so we look at 'Delivered-To'
# - mail host is running qmail virtual mailbox, prepending 109- to each address
# - 1st 'Delivered-To' is unusable so we look at the 2nd
# - Mail is deleted from the mail host.
#
# poll pop.provider.net localdomains loonytoons.org:
#  envelope 1 "Delivered-To:" qvirtual "109-"
#  user your_username with pass your_password to * here no keep


# SOME USEFUL OPTIONS
# keep - Don't delete seen messages from server
# no keep - Delete seen messages from server (default)
# fetchall - Fetch all messages whether seen or not
# no fetchall - Retrieve only new messages (default)

Create the Fetchmail log file, change its owner to fetchmail and give root write access to it (beware that if you're using the log for troubleshooting, it can grow quickly):
touch /var/log/fetchmail
chown fetchmail /var/log/fetchmail
chmod g+w /var/log/fetchmail

Usage

Start system-wide fetchmail service: /etc/init.d/fetchmail start

Stop system-wide fetchmail service: /etc/init.d/fetchmail stop

Restart system-wide fetchmail service: /etc/init.d/fetchmail restart

Tell system-wide fetchmail to start a poll cycle immediately: /etc/init.d/fetchmail awaken

Troubleshooting

With the log file set as described in our example configuration above, you can watch the log with tail -f /var/log/fetchmail
(how do we get a log to watch as verbose a log as when using debug-run? do we have to always run in debug-run mode to get this?)

Start a debug run of the system-wide fetchmail service, optionally running it under strace: /etc/init.d/fetchmail debug-run

Display Fetchmail's defaults: /usr/bin/fetchmail --configdump

Further Information

info fetchmail

/usr/share/doc/fetchmail/fetchmail-FAQ.html

/usr/share/doc/fetchmail/README.Debian.gz

SSH server (sshd)

Package(s)

Configuration

Configuration file: /etc/ssh/sshd_config

/etc/init.d/ssh start|stop|restart

To allow X windows programs to be run by people remotely logging in using SSH, in /etc/ssh/sshd_config have X11Forwarding yes (requires one of a number of corresponding configuration settings on the connecting computer).

LDAP server

Package(s)

Configuration

See these worthwhile guides for configuration instructions:

Restart slapd for changes to take using /etc/init.d/slapd restart.

Linux kernel updates

Package(s)

Installation

kernel-image is a 'pseudo package' for the Linux kernel which will list the specific kernel packages available for different kernel versions; you should install the most recent kernel available using the actual package name in the form kernel-image-<kernel-version>-<architecture>. The kernel will be installed and your old kernel version retained (if this is a kernel for '-386' that works on any x86 architecture then it gives you a fail-safe boot option in case of problems at some point), with the new kernel set as the default in the GRUB menu (in most instances the default, but not all). Pick the most recent version 2.6 kernel available. You can find out which CPU you have in your system with the command cat /proc/cpuinfo, under 'model name'.
If the Debian Installer hasn't automatically picked the specific <architecture> that matches that of your system then you should do so - i.e. for single CPU, 32-bit x86 (generically known as PC, i386, IA32, IA-32 or x86-32) architectures, the following flavours are available:

If you have multiple processors then use the '-smp' versions of some of these which are available.

Updates

You will see various messages when updating or upgrading kernels. Here are some examples.

When you use aptitude upgrade you get updated versions of the same kernel(s) you have installed. Same package name, different version of that package. For example you might get package kernel-image-2.6.8-4-686-smp (package version 2.6.8-17) updated to package version 2.6.8-17sarge1. This is the kind of message you would see in this case:

Setting up kernel-image-2.6.8-4-686-smp (2.6.8-17sarge1) ...

 You are attempting to install a kernel version that is the same as
 the version you are currently running (version 2.6.8-4-686-smp). The modules
 list is quite likely to have been changed, and the modules dependency
 file /lib/modules/2.6.8-4-686-smp/modules.dep needs to be re-built. It can
 not be built correctly right now, since the module list for the
 running kernel are likely to be different from the kernel installed.
 I am creating a new modules.dep file, but that may not be
 correct. It shall be regenerated correctly at next reboot.

 I repeat: you have to reboot in order for the modules file to be
 created correctly. Until you reboot, it may be impossible to load
 some modules. Reboot as soon as this install is finished (Do not
 reboot right now, since you may not be able to boot back up until
 installation is over, but boot immediately after). I can not stress
 that too much. You need to reboot soon.

Please Hit return to continue.

Not touching initrd symlinks since we are being reinstalled (2.6.8-17)
Not updating image symbolic links since we are being updated (2.6.8-17)
Searching for GRUB installation directory ... found: /boot/grub .
Testing for an existing GRUB menu.list file... found: /boot/grub/menu.lst .
Searching for splash image... none found, skipping...
Found kernel: /boot/vmlinuz-2.6.8-4-686-smp
Updating /boot/grub/menu.lst ... done

When you use aptitude dist-upgrade you get upgraded kernel packages themselves - actual new builds of the same kernel version (2.6.18) you have installed, bringing in bigger updates than when just the package version changes. For example you might get package kernel-image-2.6.8-3-686-smp upgraded to package kernel-image-2.6.8-4-686-smp. The whole package itself has changed, so you end up with the old kernel and the new kernel. This is the kind of message you would see in this case:

  You are running a kernel (version 2.6.8-3-686-smp) and attempting to remove
  the same version. This is a potentially disastrous action. Not only
  will /boot/vmlinuz-2.6.8-3-686-smp be removed, making it impossible to boot
  it, (you will have to take action to change your boot loader to boot
  a new kernel), it will also remove all modules under the directory
  /lib/modules/2.6.8-3-686-smp. Just having a copy of the kernel image is not
  enough, you will have to replace the modules too.

    I repeat, this is very dangerous. If at all in doubt, answer
    no. If you know exactly what you are doing, and are prepared to
    hose your system, then answer Yes.
Remove the running kernel image (not recommended) [No]?

If you say 'no' here you get this:

dpkg: error processing kernel-image-2.6.8-3-686-smp (--remove):
 subprocess pre-removal script returned error exit status 1
Errors were encountered while processing:
 kernel-image-2.6.8-3-686-smp
E: Sub-process /usr/bin/dpkg returned an error code (1)
Ack!  Something bad happened while installing packages.  Trying to recover:
Setting up kernel-image-2.6.8-4-686-smp (2.6.8-17) ...
Searching for GRUB installation directory ... found: /boot/grub .
Testing for an existing GRUB menu.list file... found: /boot/grub/menu.lst .
Searching for splash image... none found, skipping...
Found kernel: /boot/vmlinuz-2.6.8-4-686-smp
Found kernel: /boot/vmlinuz-2.6.8-3-686-smp
Updating /boot/grub/menu.lst ... done

If you say 'yes' here you get this:

Ok, proceeding with removing running kernel image.
Searching for GRUB installation directory ... found: /boot/grub .
Testing for an existing GRUB menu.list file... found: /boot/grub/menu.lst .
Searching for splash image... none found, skipping...
Found kernel: /boot/vmlinuz-2.6.8-4-686-smp
Updating /boot/grub/menu.lst ... done

The link /vmlinuz.old is a dangling link
Removing symbolic link vmlinuz.old
Unless you used the optional flag in lilo,
 you may need to re-run lilo
The link /initrd.img.old is a dangling link
Removing symbolic link initrd.img.old
Unless you used the optional flag in lilo,
 you may need to re-run lilo

...

Setting up kernel-image-2.6-686-smp (101sarge2) ...

server:/var/log# aptitude dist-upgrade
Reading Package Lists... Done
Building Dependency Tree
Reading extended state information
Initializing package states... Done
Reading task descriptions... Done
The following packages are unused and will be REMOVED:
  kernel-image-2.6.8-3-686-smp

Configuration

To see which compile-time options were set in your kernel, see the file /boot/config-<kernel version>-<Debian build version>-<architecture>.

Further Information

Changes in the 2.6 Linux kernel - prior to the present mainline kernel wiki.kernelnewbies.org/Linux26Changes

Changes in the 2.6 Linux kernel - the present mainline kernel wiki.kernelnewbies.org/LinuxChanges

'Debian Reference - Chapter 7 - The Linux kernel under Debian: www.debian.org/doc/manuals/reference/ch-kernel.en.html

KernelTrap: kerneltrap.org/

Kernel Traffic: www.kerneltraffic.org/kernel-traffic/latest.html

The Linux Kernel Mailing List (LKML): lkml.org/

The Linux Kernel Archives: kernel.org/

NFS server

Package(s)

Configuration

The userID of the user on the workstation must match the userID of a user on the server.

Add directories to share and who to share them to in /etc/exports, for example:
/home/shared 10.0.0.0/255.255.0.0(rw) 192.168.0.0/255.255.0.0(rw)

Re-export all directories in the table of exported file systems for NFS:
exportfs -ra

Further Information

Version control - Subversion

Package(s)

Configuration

This configuration is explained in more depth at http://svnbook.red-bean.com/nightly/en/svn.serverconfig.svnserve.html

In order to use Subversion's own lightweight server (as opposed to using Apache) to enable access over a network edit the following then restart inetd with /etc/init.d/inetd restart:
/etc/inetd.conf: svn stream tcp nowait svnowner /usr/bin/svnserve svnserve -i -r /usr/local/repositories
You can leave out the -r /usr/local/repositories but users will have to include the whole local path in their client software). You need to create the user svnowner and give them appropriate permissions on the subversion repository directory.

Define the name of the password file of users that can commit to the repository, and give your realm a name, by adding the following to:
/repository-directory/conf/svnserve.conf
[general] password-db = passwd
realm = My First Realm

Define users that can commit to the repository, by creating the file: /repository-directory/conf/passwd
and adding users using this syntax: [users]
harry = foopassword
sally = barpassword

Further Information

Version Control with Subversion:

Printing

Package(s)

When printing to a directly attached printer

When printing to either a directly attached or remote printer

Package installation options

cupsys-bsd asks "Do you want to set up the BSD lpd compatibility server?" - yes

When printing to a remote printer

Put the hostname or IP address of the print server in the ServerName section of the configuration file /etc/cups/client.conf. The printer should then be available to most applications to print to.

Install the Printer Driver, when the printer is directly attached

You need a PostScript printer driver (and filter, if the printer isn't a PostScript printer) for each printer, even if the printer isn't a PostScript printer. Go to the http://www.linux-foundation.org Printer Database at http://linuxprinting.org/printer_list.cgi and look up your particular printer and note which driver (and accompanying filter) it recommends using.

Install the recommended PostScript printer driver package (see previously), or if you're using an actual PostScript printer you may be getting the driver from the printer vendor.

Restart CUPS: /etc/init.d/cupsys restart

(this example is for an Epson Stylus C84, you need to change the name of the files to suit your printer)

Create the print queue, when the printer is directly attached

using the CUPS web interface

Using the command-line

If you need to remove the print queue, use lpadmin -x <printer>.

Configure the printer driver

Using the CUPS web interface

Configure Printer...

Using the command-line

lpoptions - display or set printer options and defaults. Use it to lock down a set of sensible defaults. To see the options available for your setup, use the 'docs' option like this: lp -d <printer> -o docs /etc/hosts; or use lpoptions -p <printer> -l. Usually, you can also use the media=..., sides=..., and duplex CUPS options, if there are InputSlot, MediaType, and Duplex options for your driver.

Sharing the printer

CUPS

Samba

To share printers to Windows workstations (this assumes some understanding of Samba).

This is only a rudimentary guide to setting up print sharing through Samba. For a much more complete guide see the printing section of our Samba document 'Setting up a Samba primary domain controller and file/print/software deployment server for Windows using Samba 3 on Debian 3.1 Sarge'.

Tools for working with printer queues and print jobs

Using the CUPS web interface

Should be self explanatory.

Using the command-line

(use -h IP-address with each of these to specify the IP address of the print server if using a remote printer)

Inkjet printer maintenance

With Epson Stylus printers

Using the command-line

Troubleshooting

show available devices or drivers: lpinfo

restart CUPS: /etc/init.d/cupsys restart

CUPS configuration file: /etc/cups/cupsd.conf

CUPS error log: /var/log/cups/error_log. (Change 'LogLevel warn' to 'LogLevel debug' in /etc/cups/cupsd.conf, then restart CUPS, for more verbose messages in the error log.)

Configuration for Printing to Windows Printers

(Note: add package names for installing Samba components for this to work)

Check you can connect to the Windows system: smbclient -L <computer-name> -N. If WINS isn't available you need to additionally specify the IP address with -I IP-address.

Verify that your installation of CUPS has the SMB backend by looking for a particular symbolic link: ls -l /usr/lib/cups/backend/smb. If this symbolic link doesn't exist, create it: ln -s /usr/bin/smbspool /usr/lib/cups/backend/smb

Further Information

info cupsd.conf

The Official Samba-3 HOWTO and Reference Guide - Chapter 22. CUPS Printing Support - Part III. Advanced Configuration: http://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/CUPS-printing.html

CUPS Software Administrators Manual: http://localhost:631/documentation.html or http://www.cups.org/sam.html

CUPS Software Users Manual: http://www.cups.org/sum.html

http://www.linux-foundation.org/en/OpenPrinting/Database/Foomatic includes forums for specific printer makes

CUPS Software Users Manual, http://localhost:631/documentation.html

Setting Up CUPS under Debian GNU/Linux: http://mumford1.dyndns.org/~bs7452/linuxhelp/cups.html

HP Linux Printing Project: http://hpinkjet.sourceforge.net/

Debian and Windows Shared Printing mini-HOWTO: http://www.faqs.org/docs/Linux-mini/Debian-and-Windows-Shared-Printing.html (this is a good introduction)

http://www.linuxmafia.com/faq/Debian/printing-setup.html

http://gimp-print.sourceforge.net/p_Documentation.php3

Document scanner server

Package(s)

Configuration

Follow the configuration instructions in our document 'Desktop System Setup with Debian GNU/Linux 'Sarge'' and additionally configure for sharing as described below.

saned is the SANE (Scanner Access Now Easy) daemon that allows remote clients to access image acquisition devices available on the local host.

  1. configuration file: /etc/sane.d/saned.conf - contains a list of accepted clients
  2. add this to /etc/inetd.conf:
    sane stream tcp nowait saned.saned /usr/sbin/saned saned
  3. The Debian package automatically adds this for you to /etc/services:
    sane 6566/tcp # SANE network scanner daemon
    (Note: Debian uses 'sane' where as the SANE project's documentation uses 'sane-port'. It looks as though 'sane-port' will be replaced in the IANA ports specification with 'sane')

DHCP

Package(s)

Configuration

Configuration file: /etc/dhcp3/dhcpd.conf

Internet relay chat (IRC) server using dancer

Package(s)

Configuration

dancer-ircd

The documentation in /usr/share/doc/dancer-ircd/ and /usr/share/doc/dancer-ircd-doc/ doesn't seem helpful with configuration.

dancer services

Troubleshooting

dancer-ircd

/var/log/dancer-ircd/ircd.log

Dancer services

/var/log/dancer-services/services.log

Linux Terminal Server (LTSP)

Package(s)

Configuration

Once LTSP is running and you're able to login, you'll need to install a window manager and other software. We found you just install, for example, gnome, and it just works when logging in from the workstation.
(However this seems to run counter to what is described in the Project MueKow / LTSP 5 documentation which says you need to install packages into the LTSP export directory /opt/ltsp using:
chroot /opt/ltsp/i386
aptitude install mozilla-firefox)

Further Reading

Troubleshooting

Bugs

Bugs with documentation

Telephony - Asterisk

This section is incomplete.

Package(s)

Graphical and remote administration using Webmin

Project site: http://www.webmin.com/

Package(s)

These are some of the modules. Only install those you want to use, as each has a dependency on the package it provides administration for:

Configuration

Further Information

'The Book of Webmin' or 'How I Learned to Stop Worrying and Love UNIX' by Joe Cooper: http://www.swelltech.com/support/webminguide-1.0/

"Tune your web browser to http://file-server.localdomain/cgi-bin/man/man2html to view"

UPS - Uninterruptible Power Supply Monitoring

Package(s)

Configuration

When you install the package it will automatically start it and use a sensible set of defaults, which are to monitor the first serial port and shutdown after 20 seconds of running on battery power.

Upsd uses the syslog(2) facility for status reporting when running as a daemon, so its messages will be in /var/log/syslog.

Troubleshooting

Log files

Error logs are kept that can help understand when something is broken.

When troubleshooting a problem it can be useful to keep a command-line window open displaying a program's log file, with entries appended in real time as the file grows, using: tail -f <log-file>.