Server upgrade steps

This page describes a set of steps for how to safely update a running Dante server to a newer version.

These steps should work for any version of Dante, but when upgrading from very old versions more work might be required to adapt the server configuration file.

This guide assumes that the Dante server files are found in the default locations, as listed below:

• Server binary: /usr/local/sbin/sockd
• Server config file: /etc/sockd.conf
• Server pid file: /var/run/sockd.pid

For machines where different paths are used, adjust the instructions below as appropriate.

The entire guide should be read through before starting. It is recommended that a SOCKS client is prepared that can be used to verify that the server is running correctly.

Preparation

Before starting the update, these steps should be followed:

• Verify that the Dante version currently used is working correctly by using a SOCKS client to make a connection through it. This will make it easier to know whether a problem was caused by the upgrade to the new Dante version or not.
• Backup all affected machines.
• Download the new Dante version from the Dante download page. For some platforms binaries are available, but this guide assumes that a source archive is downloaded.
• Verify that the checksum of the downloaded archive is correct.
• If a binary archive is used, check the downloaded archive with an updated virus checker.
• Consult the Dante upgrade page to check if there are any changes made in the new version that need to be considered.

To prepare for a situation where the new server version does not work as expected, create a backup of the server binary and configuration file as follows:

• cp /usr/local/sbin/sockd /usr/local/sbin/sockd.old
• cp /etc/sockd.conf /etc/sockd.conf.old

Should the update fail, having a copy of these files should be sufficient to restore operation of the old version later.

Building the new version

To compile a new version, first extract and configure the source code as shown below, for compiling Dante with the default options and installing it in the default location. Exchange dante version in the list below with the version you are installing.

• gzip -dc dante-<dante version>.tar.gz | tar xvf -
• cd dante-<dante version>
• ./configure

Consult the summary printed at the end of the configure output to ensure that all desired functionality is present. Some platforms require extra headers to be installed for functionality such as pam or GSSAPI. Some functionality might also require specific options being given to the ./configure-command if libraries are located in non-standard locations. Consult the INSTALL file in the Dante archive for details.

If all required functionality was detected in the summary printed at the end of the configure output, compile the source code:

• make

Server configuration file update

This section, and all subsequent sections, assumes that the steps in the Preparation section above has been executed and that a backup copy has been made of the old server configuration file.

Using the existing server configuration file as a basis, create a new sockd.conf file that can be used with the new Dante version. The Dante upgrade page lists changes in the latest major release, including necessary syntax changes that must be done to the configuration file.

• cp /etc/sockd.conf sockd.conf_new

Once the new configuration file is ready, it can checked for any syntactical errors using the -V option to Dante like this:

• sockd/sockd -V -f sockd.conf_new

Output will be written to the logfile specified in sockd.conf.new. This means that the logfile specified in sockd.conf.new must be consulted to see if any errors or warnings are reported there.

If no errors or warnings are reported, it should now be possible to replace the new configuration file with the current /etc/sockd.conf.

• cp sockd.conf_new /etc/sockd.conf

Stopping the old Dante server

Terminate the old server process using the following command:

• sudo kill `cat /var/run/sockd.pid`

Note that I/O-processes from the terminated Dante server might still be running at this point, continuing to serve the previously existing SOCKS clients. It is not necessary to terminate these processes, and they will automatically terminate when all existing SOCKS clients have closed their sessions.

Server installation

To install the new binaries, use make from the Dante source code directory:

• make install

The new binary should now be present under /usr/local/sbin. This can be verified with the following command:

• /usr/local/sbin/sockd -v

The version number of the new version should be printed if everything went successfully.

Then double-check that the Dante server binary and the Dante configuration file are in sync:

• /usr/local/bin/sockd -V -f /etc/sockd.conf

New server startup

With the new server configuration and binary file installed it should now be possible to start the new server.

Start the new server as you normally start Dante. E.g. the following will normally work if your site does not use special options:

• /usr/local/sbin/sockd -D -f /etc/sockd.conf

Verify using a SOCKS client that the new server version is working as expected. If the Dante configuration includes any access checks, it should be verified that these also work as expected.

If a problem is detected and it becomes necessary to revert to the old version, terminate the new server process and revert to the old version using the following steps:

• sudo kill `cat /var/run/sockd.pid`
• cp /usr/local/sbin/sockd.old /usr/local/sbin/sockd
• cp /etc/sockd.conf.old /etc/sockd.conf

Then start Dante again as it would normally be started.