Initial Assumptions

Not all client systems are the same. This guide is based on an assumed standard system with a simple boot Hard Disk Drive (HDD) / Solid State Disk (SSD) / Non-Volatile Memory Express (NVMe) device (henceforth referred to as the Boot Drive), default VGA/DVI/HDMI/DP graphics (i.e. the video outputs to a monitor without the need for special kernel drivers) and a single wired Local Area Network (LAN) / ethernet port (again without the need for special kernel drivers). Non-standard systems (e.g. those with RAID arrays, GPUs, etc) MAY work with this guide but they may also need extra configuration in order to get them to boot, display and connect properly.

Other assumptions include standard University requirements / procedures for BIOS protection, system registration, electrical safety testing (PAT), asset assignation, etc. This guide will not provide detail on these items.

For the purposes of this article, we will assume that we are building a laptop system with a single, NVMe Boot Drive. The name for the system used in this guide will be uol-lap-example01. The guide will highlight any differences between laptop and desktop builds as they arise. It will be built on the ‘Engineering’ network as we know that this VLAN will allow Satellite to netboot. Note - a system can be transferred to another subnet after the build process has completed - the relevant entries in DDI and Satellite should be adjusted accordingly.

System Registrations

The system should be named/registered with the CMDB, Asset Management and, if required, Electrical Safety systems. These registrations are outside the scope of this article.

The system must NOT be added to the Active Directory (AD) - if an AD entry exists then it must be removed as Satellite creates an item in a specified location and cannot complete if there is already another instance in place.

Network Registration

As mentioned in the Initial Assumptions, uol-lap-example01 will be built on/using the ‘IT staff’ subnet - VLAN152, 129.11.152.0/22. We will expand this guide to add other subnets as they are tested and found to work.

• Identify the MAC address of the system - e.g. uol-lap-example01’s network card is 08:00:27:DC:82:A9
• Log in to DDI https://ddi.leeds.ac.uk/ and navigate to the required subnet in the IPAM section. e.g. 129.11.152.0/22. The ‘free’ Status filter does not work in the current version of DDI so use the “add address by search function”.

• Click on the IP Address and then NEXT.

• Before completing the main form, click the icon next to ‘Create DHCP static' and set the ‘Inheritance property’ to ‘Set’ and click OK

• This will allow you tick the ‘Create DHCP static’ and the subsequent ‘Use IPAM name …’ options

• Complete the ‘MAC address’ and ‘Shortname’ sections (please ensure that you enter the shortname in lowercase) and then click ‘Next’

• Unless required, do not enter any information in the ‘Aliases Configuration’ page and just click OK

• Enter the name of the device in the ‘Name’ filter, press enter and then click the subsequent ‘Address’ that shows

• Scroll down and ‘Edit’ the ‘DHCP’ options (this section may need to be expanded first)

• Select the ‘BootP Compatible’ ‘Option category’ from the drop-down

• Enter the ‘Filename’ as ‘grub2/grubx64.efi' and the 'Next Server' as '10.129.28.33’ (this is the IP Address of satellite02) then click OK.

• Note, it can take up to an hour for the new/updated settings in DDI to propagate around the network.

Satellite Registration

Satellite02 Access

Some users may have limited access to the Satellite02 system or no access at all. If you find that you cannot perform the operations listed below then please raise a Request with the Linux team and ask them register the system on your behalf. Please include:

• system name,
• MAC address,
• IP address,
• Build subnet

Adding a New Device to Satellite02

• In a web browser, log in to https://satellite02.leeds.ac.uk with your IT credentials (note, Satellite02 is only accessible whilst on-site or via the VPN or other tunnel and has a self-signed SSL certificate which is safe to accept).

• On the left-hand sidebar select Hosts then All Hosts

• In the top-right of the ‘Hosts’ Window click ‘Create Host’

• The system will enter a random name for the computer, this can be overwritten. Set the following fields in the ‘Host’ tab:

• • Name: uol-lap-example01 [use the same Shortname as in DDI]
  • Organisation: University of Leeds
  • Location: Main Campus
  • Host Group: UoL/Client/Off-site/portable (or UoL/Client/On-site/desktop for standard, desktop systems)

• At this point the system should populate the remainder of the required items as shown below

• Do NOT click ‘Submit’ until all the required tabs have been completed
• Click on the ‘Operating Systems’ tab. Most of the fields should have already been set but the ‘Partition Table’ may need adjusting. Ensure that it is set to ‘aa_UoL_Kickstart_desktop-nvme’ for a desktop system or ‘aa_UoL_Kickstart_laptop-nvme’ for a portable/laptop/offsite system (the laptop settings also encrypt the Boot Drive). Don’t worry if the system shows an older Operating System version (e.g. 8.4) - this will be automatically updated in the final stages of the build. If the system requires a unique root password then enter it, CAREFULLY, in to the ‘Root Password’ box - otherwise the default password for that group will be used.

• Select the ‘Interfaces’ tab. One interface should be available for editing - click on the ‘Edit’ button

• The Interface dialogue box information will vary from network to network but we will use the example here to complete it. The first thing to select should be the IPv4 subnet. Adjust it relate to the subnet on which the system is currently being built, e.g. IT Staff on the 152 VLAN.

• Then complete the following required sections accordingly:

• • MAC Address: 08:00:27:DC:82:A9 [Use the MAC of the actual system]
  • Device Identifier: eth0 [this will later be changed, automatically, by the satellite installer]
  • IPv4 Address: 129.11.153.112 [Use the address of the actual system]
  • Leave all the other entries in their default state

• Check that the Interface section looks something like the figure below and then click OK

• Finally, select the ‘Additional Information’ tab and enter any relevant commentary before clicking ‘Submit’

• Satellite then shows the overview page for the new system and is ready to provide the NetBoot installation for it. There is a limited time window during which the NetBoot is available. The window is currently 6 hours. If the system NetBoot has been delayed then click ‘Cancel build' and then click ‘Build’ (with confirmation) to reset the window.

 

 

NetBooting the New Device to Install the Operating System

WARNING - 'NetBooting for Build' requires a good, stable, fast, wired connection otherwise build failures and errors may be encountered.

• Ensure that the device is able to UEFI net boot in the BIOS,

• The default option will boot automatically after a short time-out, or hit return to launch immediately

• There may be a delay of quite a few minutes with a blank screen (perhaps showing a cursor and a fair bit of network traffic) whilst the install OS loads in to memory over the network. Do NOT reboot or attempt any kind of interaction until the system prompts you - perhaps go grab a hot beverage whilst this screen is showing

• Eventually the normal boot text will start appearing

• The text install screen will then appear

(note, the green bar at the bottom shows that the system is in install mode - at this point it is possible to use another networked system to SSH in to the build process to monitor and/or interact - useful if you want to leave the system and work from another location. The ‘Install Mode - SSH Interaction’ is detailed in the standalone section, below)

• Enter the username (and then password) of an account which has rights to create/edit objects in the OU shown (this can be modified in the Satellite Parameters of the device but, by default, is in Resources/IT/OS-Builds/Linux)

• Portable/offsite devices will be prompted for a default Boot Drive encryption passphrase for use by IT staff - enter the agreed phrase (note and/or look up in Secret Server) for this system or for the IT (sys)Admin group

• The system should continue with automatic partitioning and installation

Note - occasionally the system stops at the section before ‘Progress’ (in between the === lines) because it needs further information - this is usually when the disk array isn’t as expected and requires manual intervention to specify the disk partitioning. However, normally, the install process will continue automatically.

• The system then continues to install OS and software

 

• It will eventually reboot into the new OS - a portable/offsite device will require the decryption passphrase before loading the rest of the OS

• At this stage then it might be worthwhile going to get another hot beverage. The system will continue booting to the login prompt BUT it will need to run at least one puppet agent iteration before it will allow IT accounts to log in. Once you are able to log in then sudo elevate to root ( sudo su - ) and run

puppet agent -t

repeatedly until it shows no changes. At this point reboot the system again.

If you wish to expedite this (perhaps you don’t need another hot beverage) then log in with the root account (if available) and run

puppet agent -t

repeatedly until it shows no changes. At this point reboot the system again.

• When the new device has finished rebooting (you will have to enter the decryption passphrase again if it has been set) then leave it at the login prompt and return to https://satellite02.leeds.ac.uk
• Navigate to the Hosts - All Hosts sidebar and enter a unique part of the new device’s name (e.g. its asset number) in the search box, then press return or click the search button. Identify the device in the resulting list and click the 'Edit button at the end of the row

• Now change the 'Host Group' in the 'Host' tab to either Desktop/GUI or Portable/GUI as required

• Click on the ‘Operating System’ tab and you will see that the ‘Partition Table Entry is probably empty. In order to successfully save any changes you will need to select ‘Kickstart default’ and then click 'Submit’ (the partition table entry is not important at this time as it will be reset if the system requires rebuilding)

• These changes will now need to be applied. On the host’s information page select ‘Run Ansible Roles’ under the ‘Schedule Remote Job’ drop-down

• This then loads the ‘Run Ansible Roles’ page and shows that the results are pending and the Host status is running.

• This first run will take a LONG time (perhaps quite a few hot beverages, usually over 30 minutes).

Do NOT power off or restart the system until the job has completed.

• The easiest way to check the status of the job is to go back to the Host’s overview page (Navigate to the Hosts - All Hosts sidebar and enter a unique part of the new device’s name (e.g. its asset number) in the search box, then press return or click the search button and click the link, NOT the Edit button). Then click the ‘Jobs’ button.

• The Job Invocations page will show you the ‘Run ansible roles’ job that you have just started. In the first example, below, the job is still running. You can refresh (or return to) this page until the job is marked as Succeeded.

• Wait for the Job to complete successfully. Then reboot the system so that it loads in to the GUI and that you can log in (if it is a portable system then you will need to enter the decryption passphrase)

 

 

• Then if the system is NOT portable/offsite you can move to the next step. Otherwise it is now necessary to setup the user decryption passphrase. Log back in to the system (you should be able to use the local ‘admin’ account) and run the command
  
  sudo /root/setupuserencrypt.bash
  
  This script will prompt for some information (including the initial disk decryption passphrase) and then setup the system so that the next user to log in (the system's new owner) will be prompted to enter their own decryption password.

Then log out (do not power off unless moving the device) and let the new owner know that they should attempt to remote in to the system and set their passphrase.

• When all the tasks are finished then shutdown/power off the system. The main setup is now complete.

It may be necessary to change the system’s IP/Subnet in DDI. If this is the case then Satellite will update when the system next checks in.

Install Mode - SSH Interaction

• When the base of the console screen shows a green bar then the system is in install mode - at this point it is possible to use another networked system to SSH in to the build process to monitor and/or interact - useful if you want to leave the new computer and work from another location. From another device, ssh to root@systemname and enter the password (found in Secret Server). Answer yes to ‘Are you sure you want to continue connecting?’ (note, a different item for this system may already be cached in your known_hosts file. You may need to remove the line containing the old details before being able to continue).

• Once logged in, you will be presented with an ‘anaconda root’ prompt. To access the install screen type the command tmux attach

• At this point the SSH session will switch to the Install screen and the screen on the main console will mostly resize to the same dimensions. Keyboard input in the SSH session will be echoed on the system console

• You can now continue with the initial install process from the remote session with a couple of caveats:
  
  • The screen finishes echoing at the ‘running post-install scripts’ phase.
  • When the system first reboots the session is terminated - if the device is a portable/offsite system then it will mostly stop at the screen asking for a decryption passphrase - this will have to be inputted at the console as the networking will not have been brought back up by this point.