Quick How-to

NOTE

This documentation is outdated and has been moved to an updated version on https://linux.web.cern.ch/installation/aims/aims2client/.

Introduction

This guide is intended to introduce you somewhat lightly but quickly to the new features of aims2 to enable you quickly undertake and complete an installation and have a general feel for how the new PXE installation service works. If you want to discover more about aims2 and its client-side commands please refer to the aims2client documentation. If you still have questions which the documentation fails to answer please contact Linux Support.

Prerequisites

At the moment there are some one-time tasks you'll need to complete first. Some of these prerequisites will no longer become an issue once aims2 in a full production environment, or you have used the new system for a period of time.

SOAP Lite

aims2 is implemented using the Perl SOAP::Lite libraries. You MUST have these libraries installed (or available somewhere) to use the client. The following commands (dependant on your Linux flavor) will install the SOAP Lite libraries for you.

yum install perl-SOAP-Lite

apt-get install libsoap-lite-perl

Perl Kerberos 5 libraries.

aims2 uses Kerberos 5 as its authentication mechanism. To use the client and authenticate using Kerberos you must install the appropriate libraries. The following commands (dependant on your GNU/Linux flavour) will install the Perl Kerberos 5 libraries for you.

yum install perl-Authen-Krb5

apt-get install libauthen-krb5-perl

It is assumed that your host is already configured to use Kerberos authentication at CERN. If you haven't already, please run kinit

The KRB5 service used is aims2.

Getting Started.

From now on it's presumed that your host points at the new NEXT_SERVER and you have resolved the above dependencies.

Using PrepareInstall

If you are planning on using PrepareInstall to install the devices (ie, the device is to be Quattorised), you can visit aims2prepare and come back to the following sections later.

Using aims2client

If you are not 'Quattorising' your device, then you will want to use the aims2client to register and enable your remote installation.

aims2client is the client-side software which allows you to interact with the aims2 installation service, registering hosts/devices for installation and managing PXE boot images. The following short sections will introduce you to some of the main features, but it is recommended that when you have more time you read the full aims2client documentation, although it is very simple.

Installing the client

You can install the client from SLC4 testing repository. If you have the testing repository enabled, the following will install the client for you.

yum install aims2client

To enable the testing repository on your system, edit /etc/yum.repos.d/cern-test.repo.

Please note that you will need the Perl Kerberos 5 and SOAP Lite libraries to successfully execute the client. Please see the aims2 Prerequisites for more information.

Registering/De-registering a device.

To register your device, it must be registered correctly in the Network Database with correct hardware address, users and location defined. If this information is incorrect, for example the device hardware address is different to that in the database, your remote installation will most likely fail.

To enable your host for installation, the following command would be used, where WALMART is the name of your device.

slinky@slinky:~$ aims2client addhost --hostname walmart
Host WALMART registered with aims.

To de-register (remove) the host, the command would be.

slinky@slinky:~$ aims2client remhost --hostname walmart
Host WALMART deregistered with aims.

Host Kickstart file.

To supply a kickstart file for your host, use the --kickstart option, for example.

   
slinky@slinky:~$ aims2client addhost --hostname WALMART --kickstart /afs/cern.ch/project/linux/dev/aims2project/kickstarts/walmart.ks 
Host WALMART registered with aims.

aims2 will accept kickstart locations by file system location (local fs, afs..) or http.

Kernel Boot Options.

aims2 allows you to provide your own kernel boot options at installation. For example some older pieces of hardware will require you to instruct Anaconda to use a larger chunk of memory for loading the kernel and image. To provide boot options for your host, use the --kopts options, for example.

slinky@slinky:~$ aims2client addhost --hostname WALMART --kopts "ramdisk_size=36000" 
Host WALMART registered with aims.

Do you have permission on x host?

aims2 introduces a new layer of authorisation around hosts/devices. To gain permission to install a device, aims must be able to make a reasonable connection between you (the user) and the device. The source of information for this decision is the Network Database. You must be the MAIN USER/RESPONSIBLE of a device in the Network Database to register/install the device.

If the machine is shared, that is the machine is registered to a service account in the Network Database such as lxplus204, aims will try to translate the service account (if know to it) to a list of people (ie. section/group lists). aims then checks if the requesting user a member of these lists. As soon as a connection is made between the user and the device, permission is granted.

For example, the user dengate wishes to install device slinky. In the network Database, slinky has the following main user and owner information.

• JAROSLAW.POLOK@CERN.CH
• DANIEL.ROBERT.DENGATE@CERN.CH

This information is then used to translate to NICE usernames, polok and dengate respectively. The result is that dengate would have permission to install slinky. If the user ribalba tries to register device slinky, they would be denied permission.

If user ribalba tries to register device lxplus204, they would first be checked against the Network Database fields. The result in the Network Database for device lxplus204 is

• FS.ADMINISTRATOR@CERN.CH

aims is aware that this (and similar entries) are actually service accounts and therefore require slightly different treatment. aims receives the above information and then translates it to a list of groups that it should check if the user is a a member of. Each group/list specified is checked, and dependant if the user is a member of the list or not, permission is granted or denied.

In this example, FS.ADMINISTRATOR translates to the list it-dep-fio-fs which user ribalba is a member of.

If you (the user) are a sysadmin responsible for the machines within buildings 513 (CERN Computer Centre) or 516, it is presumed that you already have permission to install the device.

Currently, this is a slight time overhead produced by these checks. This overhead will be reduced/removed in later releases.

Enabling/Disabling the host for installation.

To enable your host for installation, the pxeon command should be used, providing the name of the device and the name of the pxe media boot media you wish to use, for example.

slinky@slinky:~$ aims2client pxeon --hostname walmart --name slc46_i386
PXE enabled for WALMART using slc46_i386.

It will take 60 seconds before all pxe servers are available to reply to PXE boot requests for the host.

To disable the host for pxe boot, then the command would look like:

slinky@slinky:~$ aims2client pxeoff --hostname walmart
PXEBOOT Disabled for WALMART.

Automatic (%POST install) PXE Disable

To prevent your device going in to an endless PXE boot loop because it is still enabled and did not disable after installation, the following should be added to the %POST section of your kickstart file.

/usr/bin/wget http://linuxsoft.cern.ch/aims2server/aims2reboot.cgi

When a request is received at the above address, the calling host will be de-registered for PXE. If the device then reboots, it will fall through to localboot.

The above example can be adapted for your needs. For example, PrepareInstall uses the following:

/usr/bin/wget -O /root/aims2-deregistration.txt http://linuxsoft.cern.ch/aims2server/aims2reboot.cgi

Running man wget will give you more options to play with. The above example will store the reply to the above request at /root/aims2-deregistration.txt. The reply should contain the device name and a time-stamp.

Displaying host information

To check that your host has registered correctly, you can use the showhost command, as per example.

slinky@slinky:~$ aims2client showhost --hostname walmart
-------------------------------------
INTERFACE: 00-0C-F1-E1-DC-41
HOSTNAME: WALMART
REGISTERED: 2008/06/23 08-15-14am
STATUS: Disabled.
ENABLED: Host has not been enabled yet.
DISABLED: n/a
PXEBOOT: n/a
KOPTS: No boot options defined.
REGISTERED BY: dengate
-------------------------------------

Selecting your installation media

It's easy to see what installation media (images) are available for you to use using the showimage command as per the example.

aims2client showimage --name slc4*

This will return the all the images whose name starts with "slc4". Once you have narrowed down your search, you can view more information using the -FULL option as per the example

slinky@slinky:~$ aims2client showimage --name slc45_x86_64 -FULL

This will present you with more information on the image such as boot options, short description, the user who created the image and when it was uploaded. The command will also present any e-groups which the image is attached to. e-groups and images can be used to stop users outside your section/department/whatever from using your potentially crippling image and kernel.

At present, most images have no default anaconda options defined. It is left to the user to provide the necessary options. However it should be noted that slc5 images are provided with the default option of noipv6 to enable you to install it. Not including this option will cause peculiar behaviour.

Installing the device.

Once you have registered and enabled the host with aims you can reboot the device(s) and wait for them to install.

Known issues

Synchronization problem on AIMS2 servers (Apr 2010)

Since April 2010 we experience synchronization problems on AIMS2 boot servers resulting in systems boot failing (or booting wrong version). While we are working on the fix, please use following workaround for systems installations:

• Remove registered system(s) from AIMS2.
• Wait (at least 5 minutes to allow re-synchronization).
• Add systems(s) to AIMS2.
• Wait again (at least 5 minutes to allow re-synchronization).
• Set systems to pxeon.

This workaround shall allow to install systems in vaste majority of troublesome cases.

Anaconda Options

Sometimes anaconda will not know which interface (ethX) to use to continue the installation.

You may see that your installation has stopped and and will not continue until it has user intervention. This is due to the ksdevice option for anaconda, which takes the following values:

• link
• bootif
• ethX
• ab:cd:eg:12:35:56

For those using bootif, IPAPPEND 2 has already been defined so the boot interface variable will be passed to Anaconda for you.

Failure at %POST kickstart

If you are the person who registered the device and it fails with a fatal error during the %POST configuration of the kickstart, you will be most likely receive an email with a subject similar to:

install failed on lxb1234...

This is not an error with the PXE installation. This is an error with the %POST kickstart configuration. Debug the kickstart first.