welcome: please sign in


How to install a machine that complies with HCoop policies and will function properly as a service or user node.

For a general overview of our architecture, see SystemArchitecture. We have a semi-AutomatedSystemInstall procedure with Debian installer preseeds to instantiate common node types with ease.

Before proceeding with the AutomatedSystemInstall new nodes must be added to HCoop's infrastructure.

1. Network

After deciding on the host name through a poll of the members:

  1. Allocate an addresses from the free list on IpAddresses (and update the page!)

  2. Using the peer1 request portal, add a reverse dns mapping to the hostname
    • You cannot install the machine until the reverse dns mapping has been created; various services rely on the rdns mapping to behave correctly.
  3. Add basic node information to DomTool config

    1. Edit /afs/hcoop.net/common/etc/domtool/lib/hcoop.dtl and add definition for HOSTNAME_ip

    2. Edit /afs/hcoop.net/user/h/hc/hcoop/.domtool/hcoop.net to add a DNS entry for $HOST.hcoop.net, using HOSTNAME_ip

    3. Apply DomTool configuration (run DOMTOOL_USER=hcoop domtool hcoop.net)

    4. Synchronize DomTool library with source code git repository

2. Documentation

Add the machine to the Hardware page. KernelVirtualMachines go into a sub-section of their current physical node. Note any relevant information such as the resources available for the node, intended purpose, etc.

Make sure the machine is listed on the IpAddresses page.

After install, update the notes with any quirks of the install (ideally: none, but reality is a work in progress).

3. Add to Infrastructure

To control the node with DomTool minimally:

  • Add to Config.nodeIps

  • Add to Config.Firewall.firewallNodes

If you are configuring the node for a specific purpose, you'll need to add it to more configuration. See the DomTool documentation where it exists.

Prepare DomTool for deployment: DomTool/Installation.

Enable mail routing by adding to exim configuration on the mail server (unless Bug 939 has been fixed, in which case update this documentation with the domtool managed procedure). In the exim config directory:

  • update-exim4.conf.conf: Add to dc_relay_nets

  • conf.d/main/01_exim4-config_listmacrosdefs.conf: Add to unix_domains

  • Run update-exim4.conf

Add the server key to Kerberos. At the kadmin console ($SERVER is the fully qualified domain name):

add_principal -randkey host/$SERVER@HCOOP.NET

Update create-user to synchronize keytabs to the new node if applicable.

Create WebNode for portal according to DaemonAdmin/Portal


We've yet to install a physical node with our new installation procedure. For now see SetupNewMachines.


This document was written with using the GUI virt-manager to deploy a KernelVirtualMachine using our AutomatedSystemInstall. It's probably worth automating this with virsh/virtinst after solidifying things a bit more.

4. Update postinst

Create a post install script in the machine-template. A post install script should extract kerberos keys, install any additional hcoop config packages needed, bootstrap domtool, and install a reasonable set of base software depending on the intended use. This is the install step most in need of improvement.

5. Provision Resources

Create a new VM named after the host, select a network install using the current Debian stable, and add the preseed options specified on AutomatedSystemInstall to the kernel command line. Allocate a reasonable number of maximum cores, RAM, and disk (less than 40G is not recommended, although we are using LVM and can resize disks if needed). Set network using a shared device, currently br0:$HOST (which may be the Wrong Way (tm)).

It does appear that there is a better way than bridged networking: MacVTap in bridged mode works without manual configuration.

6. Debian Install

The installation is mostly automated.

  • Set the keyboard/language settings (accept the default), and enter the static network information specified on IpAddresses. The preseed will then be fetched and take over.

  • Create a root password (pwgen -cny with a length >= 9 is sufficient) when prompted, and store it in the password stash.

  • Confirm that the partition table should be written

After the first reboot, log in as an admin user and run the post install script to integrate it into our infrastructure. You may have to reboot the machine once more to fully complete the process. Afterward, the machine should be fully functional (in the world of the ideal at least).



InstallationProcedure (last edited 2014-12-25 14:57:14 by ClintonEbadi)