This site requires JavaScript to be enabled
An updated version of this article is available

Campus Linux Services - Building a Host

1750 views

17.0 - Last modified on 2025-11-10 Revised by Ralph Castanza

16.0 - Last modified on 2025-11-10 Revised by Raquel Johnson

15.0 - Last modified on 2025-03-13 Revised by Raquel Johnson - ADMIN

14.0 - Last modified on 2023-11-28 Revised by Thomas (he/him/his) Karches

13.0 - Last modified on 2023-10-17 Revised by Thomas (he/him/his) Karches

12.0 - Last modified on 2023-09-07 Revised by Thomas (he/him/his) Karches

11.0 - Last modified on 2023-09-07 Revised by Thomas (he/him/his) Karches

10.0 - Last modified on 2023-09-06 Revised by Thomas (he/him/his) Karches

9.0 - Last modified on 2023-07-20 Revised by Thomas (he/him/his) Karches

8.0 - Last modified on 2023-07-18 Revised by Thomas (he/him/his) Karches

7.0 - Last modified on 2022-09-06 Revised by Thomas (he/him/his) Karches

6.0 - Last modified on 2022-04-22 Revised by Thomas (he/him/his) Karches

5.0 - Last modified on 2022-04-22 Revised by Thomas (he/him/his) Karches

4.0 - Last modified on 2022-04-22 Revised by Thomas (he/him/his) Karches

3.0 - Last modified on 2022-04-20 Revised by Thomas (he/him/his) Karches

2.0 - Last modified on 2022-04-20 Revised by Thomas (he/him/his) Karches

1.0 - Created on 2022-02-15 Authored by Thomas (he/him/his) Karches

Building a Linux host in CLS

Welcome to Campus Linux Services( CLS ).

Here is a quick introduction to the environment and how to join the community as a new tenant: https://youtu.be/kijflGXYoZ0

Working with designated IT staff in your organization

Access to Infoblox, Active Directory and the CLS build environment is generally restricted to departmental or college IT staff. Those who are planning to build a Linux workstation or server for their own use should coordinate that activity with their local IT staff. This will assure that organizational conventions and procedures are followed.

Prerequisites - General

Prerequisites - CLS

Request admission as a tenant of the CLS environment by sending an email to LINUX@help.ncsu.edu with :

Alternatively, you can send a pull request to data/common.yaml to add your tenant configuration. Use the existing records as a guide. Once your pull request is merged, your tenant will be provisioned on the next Puppet run.

Building your Host

  1. Infoblox : Get an IP for your machine(s)
  2. Adding Hosts to Infoblox (video)
  3. Create Host record in Infoblox (video)
  4. Register IP in selected VLAN
  5. Add MAC address
  6. Configure PXE option (video) :
    • "PXE-CLS-Option" for PXE linux installs
    • "PXE-CLS-UEFI-Option" for UEFI PXE Linux installs

Configure Hiera data for your workstation

By default, this data is stored in the "data/nodes" directory in your control repository in a file called  : hostname.yaml To include this workstation in a group, this data would be set in the appropriate group.yaml file in "data/groups".

Hiera is used to provide configuration data for your workstation. To configure a host at a basic level, add a YAML file to your control repository that is named after the host it configures (i.e. myhost.yaml). There are more complex arrangements that solve duplication of configs and more, but those are documented elsewhere.

This example configuration : 

This configuration can be included in the <hostname>.yaml file (where <hostname> is the FQDN of your host), which is in the data/nodes directory

# hieradata/nodes/workstation.faculty.ncsu.edu.yaml
# this is an example yaml file to define the configuration 
# of a workstation. This would be typical for an owner
# with id 'faculty23' and grad students 'cagrad12' and 'jqgrad3'

# directives for higher level classification would go in manifests/site.pp

 

# Install a terminal-only workstation or server (uncomment next line)
# include role::workstation_micro

# Update the machine at midnight, every day.
profile::base::automatic_updates: "0 0 * * *"

# Reboot nightly at 2:00am.
profile::base::scheduled_reboot::schedule: "0 2 * * 0"

# Authenticate against Active Directory and use 
# local home directories (rather than AFS)
profile::auth::provider: ad
profile::auth::mkhomedir_location: local

 

# Any of these users can get a local session.
profile::auth::allow_users:
   - faculty23
   - cagrad12
   - jqgrad3

# Only `faculty23` can run `sudo`.
profile::auth::sudoers:
   - faculty23

  
# Only `faculty23` can SSH to this machine.
profile::remote_access::ssh_allow_users:
   - faculty23

## Linux malware detect : default options
# daily_scan: true
# autoupdate_signatures: '1' (yes)
# autoupdate_version: '0' (no)
# cron_prune_days: '21'

## Configure optional requirements
# - Disk partition layout (part of Foreman configuration)
# - Remote SSH access allowed? (yes,no)
# - Reboot system monthly (yes,no)
# - Update system daily (yes,no)
# - Mount remote network shares? (no, specify shares)
# - AFS support? (yes,no)
# - Use AFS home space or local home space? (AFS, local)
# - Additional software (none, specify list)
# - Printers (none, list of printers) - can this be done as part of the install?

There are more options detailed in the CLS documentation. These should be adequate for most situations

Create a host record in Foreman

Log into Foreman

Before you proceed, please note :

Select Hosts > Create Host

 

then process following the sections of the host entry form 

 

Select Host tab

Select Operating System tab

 

Note : Root password must be longer than 8 characters and relatively complex

Whether or not root is allowed to SSH to your machine is configurable via profile::remote_access::ssh_root_login and is defaulted to no, for Puppet Roles that have that profile applied.

Note: The RedHat default configuration "out of the box" will allow for root logins until puppet runs for the first time to change it

Note : Ubuntu does not allow root logins

 

Select Interfaces tab

Configure the interface that will be used to PXE boot to our deployment of Foreman

Click “Edit” (or click “Add Interface” if you want to add an additional one)

 

 

Select “OK” to close Interface dialog

 ** : required

 

Select Puppet Classes tab

Puppet Classes are currently disabled

 

Select Parameters tab

Assign any host parameters which may influence provisioning There are some parameters you may need to be aware of to set at either the host group or host level, depending on your need.

This will be typical of what you will see :

Select Additional Information tab

 

The machine will be provisioned if deployed to anything other than Bare Metal, and networking information will be assigned, if available.

After a host is created, it will automatically enter Build Mode, which can be manually toggled at any time. When a host enters Build Mode, a new provisioning token is generated, which is good for an hour.

Red Hat Enterprise Linux

RedHat operating systems will subscribe to the CDN by default in the CLS foreman. No additional configuration is required at this time.

CLS Provisioning Process

  1. Client boots, obtains DHCP lease with bootp server info
  2. Client starts PXE boot process, sending MAC address to Foreman
  3. Foreman authorizes the client based on the MAC address
  4. Foreman sends PXE templates depending on boot selection for host
  5. PXE templates will include links to kernel and initramfs images
  6. PXE templates will include links to provision templates (kickstart, etc)
  7. Client executes the templates, which provision the machine
  8. Provisioning templates are secured with a token, which expires after an hour. Client obtains the token in the initial PXE configs, auth’d via MAC.

PXE booting your host for the first time

After entering the details for your host, click "Submit". You will be redirected to the host interface for your newly created machine and "Build" will have been selected (marking your machine ready for PXE booting). Clicking "Build" tells Foreman to write a TFTP configuration for your host, which is used during the PXE boot process. If you forget to click this, the machine will chain-load to disk, by default.

PXE / UEFI PXE boot the machine. You should eventually see output from the PXE process that shows your machine pulling boot images and starting up. UEFI PXE boot may take a few seconds before any output appears. Diagnosing problems with PXE booting can be tricky. If you ever need help or want to know if your box is actually communicating with our deployment of Foreman, let us know in #cls and we can help. Some good places to start if you have trouble are:

Waiting on the first Puppet run

The CLS deployment of Foreman "releases" ownership of the host to you after bare-metal provisioning. It is likely running Puppet for the first time and will be made available to you. Log in as root if necessary, but this means that you shouldn't expect the system to be ready for an end-user after the first boot.

Puppet runtime is highly dependent on the type of host being provisioned. A role::workstation_minimal host usually builds in 12-14 minutes after OS has been installed. However a role::workstation can take more than 30-45 minutes to build. This is because a desktop environment is made up of many packages and takes time to install. Likewise, any host that uses our software profile to install many packages will take longer during the first Puppet run. This is usually not a problem, but is something to consider when it comes to support for your end-users.

When the first run completes, you will see two reports on the host interface in Foreman:

At this point, the machine is ready for folks to use. Good luck!

Information on specific regulatory builds

EPS compliant workstation

Hosts that connect to the campus network need to be EndPoint Protection Standard (EPS) compliant. This ensures that your system is protected from potential security threats on the Internet.

ALL the above profiles and settings are included to satisfy specific EPS requirements. For example, the profile::remote_access ensures compliance with EPS Encrypted Network Communications (ENC). If you need to modify or remove any of the profiles or settings during initial build or subsequent support, you are required to first obtain an approval for the exception from Security and Compliance.

 

In addition to these profiles and settings, EPS compliance also depends on essential security measures of respective OS and software packages. For example, all modern browsers support Web Reputation Filtering (WRF), which is an EPS requirement. You need to obtain an approval from Security and Compliance before disabling such functionality.

 

At the present time, there is no automated procedure to manage full disk encryption even though it is strongly recommended. You can use the following procedure to enable full disk encryption (on Ubuntu or RedHat systems). Please securely protect your encryption key. You will not be able to recover any data from the disk later if the encryption key is lost.

 

DIsk Encryption 

 

If you wish to employ full disk encryption, that will need to be configured as part of the install and is beyond the scope of this process. The CLS install process supports full disk encryption during install using a custom kickstart file, but does not escrow the key. This would have to be managed physically and would be required whenever the system booted.

 

The performance on older hardware may also be a concern as everything on the drive will be encrypted, including swap space and system partitions. 

 

The other option is to encrypt your home directory or specific partitions. This can be done after the fact on both supported systems

 

RedHat

 

Disk Encryption via LUKS - for "after the install" this process will delete the contents of your /home partition before recreating the encrypted partition. Note that the data is only protected when the disk is off...once the system is booted, all content on the disk is available



Ubuntu



CLS SPECIFIC CONTENT 

 

 

Configure a control repository

Each tenant in our deployment of Foreman will have an r10k control repository that specifies module dependencies via Puppetfile as well as node classifications via manifests/*.pp. You should use the

skeleton control repository provided by Puppetlabs. You are free to execute whatever Puppet you want out of this environment.

The traditional usage of a Puppetfile declares every dependency that your Puppet code will need to run. The Infrastructure Puppetfile will always have the full list of modules needed to run any of the shared modules maintained by the CLS. You can simply copy-paste this file into your repository, and add any additional modules you need as you go.

Check out the Example Puppetfiles for a detailed example.

Once you've pushed your repository to GitHub, grant the cls-puppet-svc GitHub user read. This allows automation in our environment to clone your control repository when changes occur.

If you wish to set up a "push-to-deploy" integration between GitHub Enterprise and Foreman, check out Using GitHub Webhooks to Automatically Deploy via r10k.

Control repository compatibility adjustments for CLS infrastructure

If you wish to make use of the shared configurations provided by CLS, one of the things you will need to do first is clean up the control repository provided by PuppetLabs a bit. The following steps should be taken:

Source - this is a copy of content generated from https://github.ncsu.edu/twk/infrastructure/blob/patch-1/docs/getting-started.md#getting-started

 

Revised by Thomas (he/him/his) Karches
Last modified 2022-04-22 16:49:10