Customize the site configuration file

Overview

The file is in a format similar to a Windows INI file in which sections are delimited by bracketed values. For more information about the ConfigParser format, see ConfigParser — Configuration file parser.

The only significant difference in the Lab Management configuration site.conf file format from the ConfigParser format is that the tokens are case-sensitive (for example, My_Token is not the same as my_token ).

The information presented here is organized by section and provides additional detail and explanation of the changes that you need to make. The sections are as follows:

Default
Monitoring settings
Managed hardware information
Lab Management Manager
Primary Active Directory server
Arbitrary Infrastructure nodes -- optional
Windows Deployment Services settings -- optional
Authentication setup -- CTF (or CEE) (the authentication not chosen is optional)
Samba exports--optional (beyond those shares that Lab Management requires)
SSL Certificate settings -- optional
Solaris SPARC Bootserver settings -- optional
Project Build Library settings
Lab Management HTTP proxy settings -- optional
License keys
Backup settings
rysnc configuration
Network (subnet definitions)

Default

The Default section is required and contains site-wide defaults. It contains global definitions such as: where your data assets are placed, the database, the Subversion repository, your branded templates and graphics, and all the other data essentials. The directory backup should be large enough to contain these assets.

You can add other sections to override specific values in the generated runtime config file, although this is not recommended and will not be discussed in this document.

Those elements that have comments in this section take the default values unless you explicitly set them.

Note:

The values for the tokens in the sample-site.conf file cannot contain semicolons (;). Semicolons are used in the config file format to indicate a comment character: this is the end of this configuration key and nothing after the semicolon on each line will be parsed.

All columns must start from column 1 -- you cannot have spaces before an entry.

Other sections in the sample-site.conf file are commented out entirely because they are optional.

The elements in the Default section include:

Root of Lab Management the data directory:
```
 cubit_data_dir = /u1/cubit/data
```
Lab Management domain -- the domain that is under management. It is not this host's domain.
```
 cubit_domain = cubit.example.com
```
Authentication variable -- CTF (or CEE).
```
 cubit_auth_scheme = ctf
```
Lab Management root bind and search bind passwords -- these apply only to the Primary Active Directory server.
```
 cubit_root_bind_pwd = CHANGEME
 cubit_search_bind_pwd = CHANGEME
```
Lab Management node root password -- this is the root password for managed Linux or Solaris nodes. It is enabled in one of two ways: use the plain text token or the two hash tokens (for extra security). If you choose to use the two hash tokens, you never have to write down your password in plain text but you must know what the hash corresponds to.
You must choose one of the token formats to define the root password -- either number 1 (for the plain text token) or 2 and 3 (that, together, define the hash tokens):
1. cubit_nodes_root_password = CHANGEME (to define the plain text password)
2. cubit_nodes_root_md5_hash = CHANGEME (to define the hash token for Linux nodes)
3. cubit_nodes_root_des_hash = CHANGEME (to define the hash token for Solaris nodes)
NFS Servers -- if the following tokens are defined, the mount is coming from a remote NFS server:
```
 nfs_homedir_remote_hostname = %(cubit_mgr_hostname)s
```
If the remote host is the Lab Management Manager, this is the directory path on the Lab Management Manager. Otherwise, the name of the volume is on the remote server:
```
 nfs_homedir_remote_volume = %(cubit_chroot_dir)s
```

NFS Home Directories:

 homedir_local_mountpoint = %(cubit_chroot_dir)s
 homedir_local_export_options = rw.sync

NFS O/S Directories:
```
  osdir_local_mountpoint = /public
```
Remote NFS Servers:
If the following tokens are defined, the mount point is coming from a remote NFS server:
```
 nfs_osdir_remote_address = 123.123.123.123
 nfs_osdir_remote_hostname = %(cubit_mgr_hostname)s
```
Remote NFS Volumes:
If the remote host is the Lab Management Manager, this is the directory path on the Lab Management Manager. Otherwise, it is the name of the volume on the remote server:
```
 nfs_osdir_remote_volume = /public
```
Lab Management HTTP user and password -- the Lab Management user created to have internal access to the autoinst repository and the associated plain text password to gain access to it.
```
 cubit_http_user = cubitrepo
 cubit_http_user_password = CHANGEME
```
Lab Management Client node variables -- define the rebooting capabilities for HP machines with iLO/RILOE support or Sun machines with ALOM support.
```
 cubit_ilo_user = cubit
 cubit_ilo_user_password = CHANGEME
                    
 cubit_alom_user = cubit
 cubit_alom_user_password = CHANGEME
```
VMware vSphere: ESX/ESXi 4.0:
This is used for logging into the ESX server via the API to manage guest nodes
```
 cubit_esx_user = cubit
 cubit_esx_user_pwd = CHANGEME
```
APC power strip -- used to powercycle Client nodes by simulating a power failure.
```
 cubit_apcpower_snmp_pass = CHANGEME
```
Email notification -- a list of email addresses, separated by commas, to receive notifications of system problems and other important messages.
```
 cubit_admin_email = you@example.com
```
Forwarding DNS Servers -- a list of IP addresses, separated by spaces.
```
 cubit_forward_dns = 192.168.88.1 192.168.89.1 192.168.90.1
```
Maximum file upload size -- the maximum size of any one file uploaded to Lab Management. The default is 8 GB.
```
 cubit_max_file_upload_bytes = 8589934592
```
Lab Management session timeout -- the number of minutes before the Web login times out when it is idle. The default is 120 (2 hours).
```
 cubit_session_timeout = 120
```
Server time zone -- the ability to host a server that displays time in a different time zone other than the one it resides in. The time zones are specified using the Olson time zone database and handled with the pytz library. For example, Pacific Standard Time (PST) is US/Pacific or America/Los Angeles. India Standard Time (IST) is Asia/Calcutta. Eastern Standard Time (EST) is US/Eastern. The default is the US/Pacific time zone.
```
 cubit_server_timezone = US/Pacific
```
Log level-- specify the types of log information that you want to capture. The valid levels are: CRITICAL, DEBUG, ERROR, FATAL, INFO. The default is INFO.
```
 cubit_log_level = INFO
```
Forwarding ports -- enables specific ports and ranges of ports to be forwarded via the port forwarding feature. Specify a list of ports separated by commas and specify port ranges using hyphens. The default is ports 50001 - 52000.
```
 cubit_ports_forward = 50001-52000
```
API Key Expiration -- specifies the amount of time in days that the API key expires. The default is 0, which means never expire the API key.
```
 cubit_restapi_key_expiry = 0
```
NTPD key information (optional, if your NTP setup requires this)
```
 cubit_ntpd_key_id = 10001
 cubit_ntpd_key_value = CHANGEME
```
Apache Proxy Timeout token, used by Host URL Mapping:
```
 cubit_http_proxytimeout = 300
```

Monitoring settings

Use this section to determine the kind of monitoring that this Lab Management installation supports:

 cubit_monitor_action = monitoring type

The valid values for the monitoring type are:

send_bb_alert -- if you are using Big Brother monitoring. Specify the IP address of the Big Brother Server:
```
 cubit_bb_monitor_ip = 192.168.204.4
```
send_ng_alert -- if you are using Nagios monitoring.
page_poc -- if you are using simple e-mail alerts. Specify a list of e-mail addresses, separated by spaces, to receive message notifications:
```
 cubit_monitor_alert_email = you@example.com
```

Managed hardware information

This section specifies information on the types of host architecture that Lab Management will manage -- the settings should reflect the hardware in your comapny's setup. Here's an example:

 [host]
 cpu_archs = i386, sun4u, x86_64, sun4v
 cpu_names = Xeon, Ultrasparc III, Ultrasparc IIIi, Ultrasparc IV, Pentium III, Pentium IV, Athlon, Opteron
 vendors = Sun, HP, Generic
 defaultvendor = Collabnet
 models = HP DL320, HP DL380, HP DL360, Generic, Sun V210, HP DL145, Rackable, HP BL460c

In addition, you'll also need to modify hardware.conf (after you install Lab Management) in the data directory. You'll need one section for each hardware model. For example:

 [HP DL380]
 Solaris_Interface_Name = primary
 LOM_Type = ilo
                
 [Sun V210]
 Solaris_Interface_Name = bge0
 LOM_Type = alom

Manager

This section is for the Lab Management Manager server. This description is informational, but contains the default settings for the Manager. We strongly recommend that you not change these settings unless you need to.

Note: If the Manager is deployed as a guest, for example, on an ESX server, you need to set parent_hostname attribute:

 parent_hostname = myparent.example.com

 [infrastructure:mgr]
 hostname = %(cubit_mgr_hostname)s
 profile_name = rhel5.4_base_i386
 install_mode = kickstart-net 
 cubit_manager = %(cubit_mgr)s
 mgr_public_gateway = %(cubit_mgr_gateway)s

Primary Active Directory server

Use this section to specify the information that Lab Management uses for the Primary Active Directory server:

 [infrastructure:primary_ad_server]
 ip_address = 192.168.204.2
 parent_hostname = %(cubit_mgr_hostname)s
 hostname = ad.%(cubit_domain)s

ip_address -- the IP address of the Primary Active Directory server (the default assumes a local virtual machine).
parent_hostname -- the hostname of the machine (a physical Infrastructure node) that the Active Directory server is running on. It defaults to the value of the 'hostname' command.
hostname -- the hostname of the Active Directory server. You are strongly encouraged to use the default hostname provided.

If the Active Directory server is hosted as a VM on the Manager node:

 parent_hostname = %(cubit_mgr_hostname)s

If your Primary Active Directory server also acts as Windows Deployment Services (WDS) server, uncomment following line:

 wds_server = True

Windows Deployment Services server

This section is relevant only if you're supporting vSphere ESX servers. See the Lab Management 2.3 Pre-upgrade steps for more on configuring site options, and Post-upgrade steps for the 2 choices you have for WDS support. If your Active Directory server is not acting as the WDS server, you need to uncomment the following section to create a separate WDS server:

 [infrastructure:wds]
 ip_address = 10.1.54.7
 parent_hostname = %(cubit_mgr_hostname)s
 hostname = wds.%(cubit_domain)s 
 descr = Windows Deployment Server
 wds_server = True
 profile_name = Windows2k3stdR2_wds
             
 memsize = 1024
 memsize_unit = MB
 disksize = 20
 disksize_unit = GB
 mac_addr = 00:50:56:01:b2:c3

Arbitrary Infrastructure nodes

Here you can optionally define additional, arbitrary infrastructure nodes for Lab Management to interact with -- these hosts will NOT appear in the UI, and cannot be used to allocate hosts from. Nodes are defined here because they contribute to the larger infrastructure of the installation, and don't require user access. Examples would be a machine providing Windows Deployment Services, a VMWare-vCenter server, and so on.

The following roughly defines the minimum set of values required to define an infrastructure node:

 [infrastructure:my_host_label]
  ip_address = 192.168.204.5
  hostname = my_host_name.$(cubit_domain)s
  profile_name = esx_4.0u1
  mac_addr = 00:00:00:00:00:00
  install_mode = unmanaged

Any number of additional fields may be defined; some settings may imply specific defaults (for example, an esx-type host defaults to "install_mode=unmanaged"), and may in turn imply additional required fields (an esx-type profile in turn requires that port_group, resource_pool, and datastore be defined). A rough example of the additional fields an esx-type node would require:

 resource_pool = Resources
 port_group = VM Network
 datastore = datastore1

Authentication setup

Use this section to specify the authentication for your configuration as CTF or LDAP. Depending on the authentication type that you are using, remove the comments for the applicable section and set the relevant values.

Note: Older versions of the file may contain a section for "sfee" -- this is incorrect; you need to replace it with the "ctf" section.

Here's an example for CTF:

[ctf]
 ctf_domain = ctf.example.com 
 ctf_version = 5
 ctf_scheme = http
 readonly_superuser_name = rootreader
 readonly_superuser_password = CHANGEME

Note: Older versions of the file may contain a section for "sfee" -- this is incorrect; you need to replace it with the "ctf" section.

To configure Single Sign On to the Lab Management site (default is False):

 allow_sso = True

To configure LDAP:

 [ldap]
 external_ldap_base_dn = dc=ldap,dc=example,dc=com 
 external_ldap_user_base_dn = ou=user,dc=ldap,dc=example,dc=com 
 external_ldap_group_base_dn = ou=group,dc=ldap,dc=example,dc=com 
 domain_controller = ldap.example.com 
 domain_controller_address = 192.168.204.5
 readonly_dn = CHANGEME 
 readonly_password = CHANGEME

For domain_admin_users and domain_admin_groups, enter comma-separated lists of valid SAM account names.

 domain_admin_users = 
 domain_admin_groups = CHANGEME

You can have one of these values for use_ssl_tls:

0 for no SSL/TLS
1 for try to use SSL/TLS if possible
2 for use SSL/TLS mandatory (throws exception on failure)

 use_ssl_tls = 1

Protocol and port -- you're advised not to change these; if you must change them, make sure they align correctly with use_ssl_tls, as this will generally impact the how the connection is initialized. Protocol should be either "ldap" or "ldaps"; port should be 389 (or 636 for SSL).

 protocol = ldap
 port = 389 
 Optional backup domain controller, if used:
 backup_domain_controller = ldap-backup.example.com 
 backup_domain_controller_address = 192.168.204.6

Samba exports

Use this section if you want to specify additional Samba shares above those Samba shares that Lab Management requires. Specify a single Samba share using a special format. The only requirements are:

Each Samba share must start with [samba: to be recognized.
The label following the colon (:) must be a unique identifier.
Each line in this section, token=value, corresponds to a Samba option to be set, where token must be a valid Samba option name.

You can specify as many Samba shares as you want. The Samba format is:

 [samba:sample]
 description = Example samba share
 name = Sample
 path = /path/to/export
 users = @__cubitu
 readonly = Yes
 browseable = Yes

SSL Certificate settings

Use this section if you are providing your own certificate. Uncomment this section and specify the certificate and the keyfile to use.

If you do not provide your own certificate, a self-signed certificate is generated. Optionally, you can supply a list of intermediate certificates, separated by spaces.

For example:

 [ssl_certificate]
 install_ssl_cert = /path/to/server.crt
 install_ssl_cert_key = /path/to/server.key
 install_ssl_intermediate_certs = cert1 cert2 cert3

Solaris SPARC Bootserver Settings

Use this section if your setup uses a Solaris SPARC Bootserver. Uncomment this section and set the following options as shown in the example:

 [miniroot]
 ip_address = 192.168.204.3
 hostname = %(cubit_mgr_hostname)s

Note: The example assumes that the Solaris SPARC Bootserver is a local virtual machine.

Lab Management HTTP Proxy Settings

These settings are used by profiles when you need to install packages from a third part repository and you need a proxy to access it.

Uncomment this section and set all of the following options as shown in the example:

 [cubit_http_proxy]
 proxy_url = http://proxy.example.com
 proxy_user = CHANGEME
 proxy_password = CHANGEME

Project Build Library Settings

Use the [pbl]section to specify the maximum size for file uploads and whether to allow guest access.

 max_file_upload_bytes = 8589934592

To allow domain-level guest access to PBL, set the following token to 1, (or 0 to deny access). If allowed at the domain level, project administrators can enable guest access to PBL for their projects.

 allow_guest_access = 1

For more on PBL, see:

License Keys

This section specifies the required license keys for the Lab Management installation. Specify simple licenses, consisting of a product name and corresponding license key, in the [licenses] section, in the form "prod_name = key".

You must have a valid Windows-2k3stdR2 key for the Primary Active Directory server. All other keys are optional depending on the profiles that your installation supports:

Important: These tokens are case-sensitive. Failure to enter correct values will result in nodes not building properly.

 [licenses]           
 Windows-2k3stdR2 = xxxxx-xxxxx-xxxxx-xxxxx
 Windows-xp_pro = xxxxx-xxxxx-xxxxx-xxxxx
 Windows-2k3std = xxxxx-xxxxx-xxxxx-xxxxx
 Windows-2000Svr = xxxxx-xxxxx-xxxxx-xxxxx
 RHEL-5 = xxxxxxxxxxxxxxxx

Backup settings

Use the options in the [backup] section control how the Lab Management Manager should be backed up.

Typically critical settings of the Manager are backed up. Data and Infrastructure node guests are not backed up -- [cubit_data] and VMware guest nodes do not need to be backed up regularly because of the time it takes, the size of the dataset and the service interruption during the backup. In addition, if [cubit_data] and guest nodes are on a NetApp volume, there is really no need for doing so. It takes merely seconds to do system info backup and there is no service interruption either.

Do you want to do a backup -- valid values are yes or no, and default = no

 backup_enabled = no

To only back up system information (default) :

 backup_command =  %(cubit_runtime_dir)s/bin/cubit_backup.py --skip_vm --skip_data

To back up system information and all guest nodes on the Manager node:

 backup_command =  %(cubit_runtime_dir)s/bin/cubit_backup.py --skip_data

To back up everything:

 backup_command =  %(cubit_runtime_dir)s/bin/cubit_backup.py

Location where backups are stored -- it MUST be outside of the cubit_data_directory! Each backup is time-stamped. For example: [backup_directory]/20081101030000

 backup_directory = /u1/cubit/backup

How often to do backups -- valid choices are hourly, daily, weekly, or monthly, the default is daily.

 interval = daily

When to do the backup:

For interval = daily, the backup runs at {run_at} hour on each day.
For interval = weekly, the backup runs at {run_at} hour on each Sunday.
For interval = Month, the backup runs at {run_at} hour on first day of the month.

The value for run_at should be between 00 and 23, and the default is 3am.

 run_at = 03

`rsync` configuration

Some forms of virtual host migration use rsync. This option controls the range of ports used by rsync. Depending on your company's security policies you might need to restrict change the range -- the range defaults to 9000-10000.

[rsync]
 rsync_port_range = 9000-10000

Network settings

Use this section to specify the network that the Lab Management domain manages. You need at least 1 section for each subnet a guest will be residing in.

Note: Network blocks must be specified in CIDR (x.x.x.x/m) notation.

The subnets are created differently for the three types of Lab Management deployments:

Direct-Access Deployment -- all subnets are routed
Important: You are strongly advised to use direct-access deployment for all guest node networks.
Isolated-Access Deployment -- all subnets are non-routed
Mixed-Access Deployment -- both routed and non-routed subnets are present

For example, consider the sample subnet, 192.168.204.0/24, defined below: To provide a textual description of this subnet, which appears in the Lab Management web interface:

description = My first Lab Management subnet

To specify the IP address of the Lab Management Manager on this subnet:

 mgr_subnet_ip = 192.168.204.1

Typically, this is the first available address on the subnet.

To specify the priority that this network block should take, relative to other network blocks:

 priority = 1

The priority token affects how managed hostnames are generated: lower priorities get earlier blocks. For example, if this block has a DHCP range of 11-254 and a priority of 1, this network is assigned managed hostnames from cu001.[cubit_domain] to cu244.[cubit_domain]

To indicate whether the subnet is routed, use yes or no as valid values:

 routed = no

To specify a default gateway for hosts located on this subnet:

 gateway = 192.168.204.1

Typically, for a routed subnet, the gateway is a router interface. For non-routed subnet, the gateway is the IP of the Lab Management Manager on this subnet.

To specify a DHCP range (which must be a consecutive range) to assign to Client nodes on this subnet:

 dhcp_range_start = 11
 dhcp_range_end = 254

Note: You are strongly advised to reserve the first 10 IP addresses on the subnet for Lab Management Infrastructure nodes. If this is a Mixed-Access deployment, you must reserve these addresses from the routed subnet even if you do not currently need them. Reserving the IP addresses in advance provides room for growth and eliminates the difficulty in adding them later to accommodate more Infrastructure Nodes as your Lab Management environment grows.

VMWare bridged netork for this subnet -- if this subnet is on eth0, the vnet is assumed to be 'vmnet0'; if the subnet is on eth1, 'vmnet2' is assumed (vmnet1 is used by vmware for other purposes). If the subnet is not on either of these interfaces, or if it is necessary to explicitly set the interface, you can do so here.

 vnet_interface = vmnet0

For more on networks in Lab Management, see:

Advanced configuration

As an optional task, you might need to override some of the options which do not appear in the sample-site.conf file.

This advanced feature enables you to specify a particular parameter (such as generating a runtime setup) in the sample-site.conf file. The sample-site.conf file is then integrated later with a larger file called a cubit-runtime.conf file.

If you have questions about advanced configurations options, contact CollabNet Support.