ClueNet:Server Setup
From ClueWiki
Cluenet is currently making some major changes to their internal infrastructure and the setup of accounts. As such, server configuration has to change as well. The new distconf2 system should make setting up servers with Cluenet very easy. Here's an explanation on how to set up a new server to integrate with Cluenet, or how to reconfigure an existing Cluenet server to work with the new infrastructure. Note that all of these instructions are designed for Debian systems and may require modification for other distro's. Read down this page in order for instructions.
Contents |
[edit] Cluenet SSL CA Certificate
The new Cluenet server configuration will be more secure in several ways than the old configuration. One of these ways is that important connections that used to be unencrypted will now be encrypted, and all encrypted connections will be verified to prevent man in the middle attacks. Many of these verifiable connections depend on having the Cluenet SSL CA Certificate. You can find the CA certificate here. Save that file on your server under the name /etc/ssl/certs/Cluenet.pem (this is the standard path on Debian machines). You can do this with this command:
wget -O /etc/ssl/certs/Cluenet.pem http://noc.cluenet.org/cluenet-ca.crt
If you believe that you have an insecure connection and would like to get the CA certificate over a more reliable medium, contact an admin.
[edit] Packages
All Cluenet servers should have the following packages installed. If you are not running a Debian system, you will have to figure out how to install each of these packages on your own distribution. The following command will install the necessary packages:
apt-get install heimdal-clients heimdal-docs heimdal-kcm heimdal-servers libgssapi4-heimdal libpam-heimdal libsasl2-modules-gssapi-heimdal libsasl2 libsasl2-modules-ldap ldap-utils libnss-ldap libpam-ldap libpam-cracklib libldap2 nscd ssh-krb5 ntpdate ntp
[edit] DistConf2
DistConf2 is similar to the original DistConf scripts in that they distribute configuration from a central server to all nodes. However, DistConf2 is a more flexible and configurable system, and also uses SSL for more secure configuration transmissions. DistConf2 is arranged in units of modules. Each module provides a script to download and install default configuration information for one service on the machine.
DistConf2 is installed in /etc/cluenet/distconf2/ . In this directory, there are several files. The "defaults" file provides global default configuration options for distconf2 modules. The "config" file provides the global configuration options that are used by all the distconf2 modules. You should not modify the defaults files, because this is automatically overwritten if new configuration options are added. Instead, modify the config file if you need to change any options.
There are also two scripts in /etc/cluenet/distconf2/ . The install_module.sh script will install a module on the system and configure it for updates. The update_modules.sh script runs all of the module scripts to update configuration information, and should probably be installed in a crontab.
The /etc/cluenet/distconf2/modules/ directory contains all the information about specific modules. Each module normally has three files associated with it. MODULENAME.defaults provides the default configuration for that module. Again, this should not be modified, because it is automatically updated and overwritten. MODULENAME.gen is a script that generates the configuration information. MODULENAME.sh is the actual module script that downloads updated defaults and new gen scripts. There is an optional fourth file that is not installed by default, but which most modules support. If MODULENAME.conf exists, it is used for module-specific configuration options that override global options. This is normally not necessary. If you want to change a module's configuration option from the default, it should normally go in the global /etc/cluenet/distconf2/config file.
The configuration file format is self-explanatory. In fact, it just sets variables like a bash script does. When a module runs, the configuration files are loaded in this order, and the last option specified takes precedence:
- /etc/cluenet/distconf2/modules/MODULENAME.defaults
- /etc/cluenet/distconf2/defaults
- /etc/cluenet/distconf2/config
- /etc/cluenet/distconf2/modules/MODULENAME.conf (if it exists)
To install distconf2, you need to download the installer script into a directory. I usually use /root, but anywhere is fine. The distconf2 installer script can be found here. You can download it with this command:
wget --ca-certificate=/etc/ssl/certs/Cluenet.pem https://ssl.cluenet.org/noc/distconf2/base/distconf2-installer.sh
There are a few configuration options at the top of the installer script that you can look at and modify, but the defaults should be fine. Before you can run the installer script, you'll have to chmod it:
chmod +x distconf2-installer.sh
Then, to run it, as root:
./distconf2-installer.sh
This should print out a few messages about the install process and install the basic setup in /etc/cluenet/distconf2/ . Note that it does not install any modules by default, and you will have to install the modules by yourself.
To install a module, cd to /etc/cluenet/distconf2/ and run ./install_module.sh MODULENAME . The modules and configuration options are listed below in the order that you should install them. After you install a module, you should first look at its configuration options. You can view all the options and the defaults for those options by looking at /etc/cluenet/distconf2/modules/MODULENAME.defaults . If you want to change a configuration option, do NOT change it in the defaults file, because it will be overwritten. Instead, add it to the /etc/cluenet/distconf2/config file.
After you install a module, it will not be automatically run. You should run it manually the first time, after you install a module and change any settings that you need to change. You can run a module manually by typing:
/etc/cluenet/distconf2/modules/MODULENAME.sh
After you make sure that a module runs fine, it should be safe to run it automatically. Adding the /etc/cluenet/distconf2/update_modules.sh script to root's crontab will cause all modules to automatically run at scheduled times. It shouldn't be necessary to run the modules more frequently than once a day.
So, here's an overview of the whole process:
- Run the distconf2 installer script.
- Install a module (with the /etc/cluenet/distconf2/install_module.sh script).
- Change any module configuration that is necessary.
- Run the module for the first time (/etc/cluenet/distconf2/modules/MODULENAME.sh).
- If applicable, test to make sure the module is working.
- Return to step 2, until all relevant modules are installed.
- Add the automatic updater script (/etc/cluenet/distconf2/update_modules.sh) to root's crontab, to execute once a day.
[edit] krb5.conf
The krb5.conf module installs and configures the /etc/krb5.conf file. This file is necessary for Kerberos to function on the system. There is only one setting for the krb5.conf module that you might want to change, and that is the KRB5NAT setting. If set to "yes" (as is the default) part of the Kerberos security measures are turned off to allow it to function behind NAT. If your server is not behind NAT, you can set this option to "no".
After you install the krb5.conf module, you should test to make sure that Kerberos is functioning. You can test this with the command:
kinit YOURUSERNAME@CLUENET.ORG
[edit] ldap
The ldap module installs and configures the /etc/ldap/ldap.conf file. This file specifies the system-wide LDAP configuration. The default module settings should be fine for most (Debian) systems.
After you install the ldap module, you should test it. First of all, run this command to see all publicly accessible database information:
ldapsearch -x
Then, make sure GSSAPI authentication works by using kinit to authenticate for your username, and then running this command:
ldapsearch uid=USERNAME
That should display all information that you have access to view about yourself.
[edit] nss_ldap
The nss_ldap module sets up the libnss-ldap configuration file. There are two important settings that you might want to change here: LDAPCHECKHOST (default no) and LDAPCHECKSERVICE (default yes). These specify whether or not users are allowed access to your system based on the host attribute and authorizedService attribute, respectively. The defaults are usually fine. Set LDAPCHECKHOST to yes if you want to allow users access to your system only if specifically allowed in LDAP. Don't set LDAPCHECKSERVICE to no unless you want all users to have access to your system, regardless of whether they have earned SSH privileges. These settings are also shared by pam_ldap, so if you change them, change them in the global distconf2 configuration file.
Once you install nss_ldap, there isn't really a way to test it until you install the nsswitch module. See below.
[edit] nsswitch
The nsswitch module just adds ldap entries to /etc/nsswitch.conf . There aren't really any configuration options to change.
Once you install the nsswitch module, you should be able to test nss_ldap. First of all, removed the cached information that nscd keeps, so it doesn't interfere:
nscd -i passwd
Then, use this command to test nss_ldap:
id USERNAME
This should print out something similar to the following:
# id crispy uid=25001(crispy) gid=25000(g-users) groups=25000(g-users)
[edit] pam_ldap
The pam_ldap module installs the pam_ldap configuration file which controls authentication and authorization via PAM. The configuration options are almost the same as the nss_ldap module - see above.
There's not a good way to test the pam_ldap module until PAM is configured to use it. See below.
[edit] pam
The pam module distributes the Cluenet PAM configuration. Note that this will probably have to be heavily modified for any distribution other than Debian. After this module is installed, you should be able to log in to ssh (if you have access to the host and service) with your LDAP/Kerberos username and password.
[edit] logindefs
This module doesn't actually replace the login.defs file, so all of the other options in the file can be modified normally. It just modifies the max UID and GID options so that the useradd program doesn't create local users that conflict with LDAP user IDs.
[edit] sshd
All this module does is adds GSSAPI authentication to the sshd configuration file. Like logindefs, it doesn't actually modify the rest of the file, or replace it.
[edit] Reminders
After you verify that all the modules are working, remember to add the module updater script to root's crontab so configuration is automatically updated. Also remember to pay attention to the admin mailing list and IRC channel so you can add new modules as they are created to keep your server as up to date as possible.
If you're upgrading from the original DistConf, make sure that you delete all the /etc/cluenet/distconf files first, and remember to remove the original DistConf updater from the crontab.
[edit] Kerberos Configuration
For people to get Kerberos tickets for your server (which are necessary for passwordless logins via SSH and a few other services), your server will need to have a host principal added to the Cluenet Kerberos database. Ask an admin to do this for you, and give you the keytab.
Note that, for most services, true Kerberos authentication (with transparently acquired tickets, at least) will not work unless the server has proper reverse DNS set up. Ie, the reverse DNS record (to the .cluenet.org suffix) needs to match the forward (A) record. Only your ISP can change your reverse DNS. The only server we know to have this is Delta.
[edit] User Status Poller
When a user account is suspended or deleted, the user is prevented from logging in by removing their password from their LDAP account and expiring their Kerberos principal. However, this does not solve the issue of killing running processes or making user files inaccessible to system daemons (such as public_html directories to apache). To do this, a separate script has to be periodically run to make sure that the local user status corresponds with the user status in LDAP.
This script essentially fetches a list of all LDAP users from the LDAP directory and does certain sets of instructions on users in each of the three categories: Normal, Suspended, and Deleted. At the time this was written, the instructions for normal users are to make sure that both their home directories and crontabs are accessible to themselves. The instructions for suspended users is to kill all user processes, chmod the home directory to 000, chmod the user crontab to 000, and removing any existing at jobs that the user may have. The instructions for deleted users are very similar, except they delete data instead of chmod'ing it.
You can get our recommended poller script (which you can also use as a framework for designing your own) from here. The standard location for this script is in /etc/cluenet/ .
Because it's a poller script, it does have to be run periodically, and as such, should be put in root's crontab. However, do NOT make it execute too frequently. None of the fetched data is cached locally because it doesn't go through nscd, and if every server fetched entire user lists very frequently, it would put a large load on the LDAP server. Running the script every half hour should be sufficient.
[edit] Other Service Configuration
There are a number of other services that you should set up at Cluenet Common Services, as well as any other specific services you want to provide for your users.
