NCI Bundles_Getting Started - ACCESS-NRI/accessdev-Trac-archive GitHub Wiki

#!div style="max-width: 1000px;"
[PageOutline](/ACCESS-NRI/accessdev-Trac-archive/wiki/PageOutline)
# Starting Out on the NCI NeCTAR Cloud

## Requesting a Cloud Account

Cloud accounts must be requested by emailing [email protected]

## Bundle Structure

The NCI Bundle system can be downloaded from `[email protected]:/nci/puppet`

 * **puppet/**
  * **hieradata/** - Hiera configuration files for setting Puppet default arguments
  * **manifests/** - Contains the Puppet entry point `site.pp`
  * **modules/** - Contains Puppet modules that can be used to configure the system
  * **corefw/** - NCI provided modules
  * **private/** - Contains sensitive information
  * **tools/** - VM Boot scripts

## Booting a VM

To boot a VM you will need your NCI OpenStack credentials loaded in your environment. If you're running on _cloudlogin_ this should be done automatically, if you're working from your own computer you will need to install [python-novaclient](https://pypi.python.org/pypi/python-novaclient) (e.g. `pip install --user python-novaclient`), copy the file `~/.nci-os-creds-${USER}.sh` from _cloudlogin_ and then source that into your environment.

## Default Settings

By default the NCI Puppet repository will apply the Puppet class **bundle::role::default**. This class has the following effects:

 * Load the class **bundle::project::common**
   * Load the class **bundle::nci::baseline**
     * Load the class **nci::puppet**
       * Creates a symlink `/puppet` -> `/etc/puppet`
       * Makes sure that `/puppet/private` is only visible to root
       * Installs bash
       * Creates a script `/usr/local/sbin/puppet-update`
       * Sets up root's `.vimrc` file
     * Load the class **bundle::nci::networking**
       * Load the class **nci::resolv_conf**
         * Sets up DHCP
       * Load the class **nci::hostname**
         * Sets VM hostname in various places
       * Load the class **nci::firewall**
         * Sets up an iptables firewall
     * Load the class **nci::dirs::home**
       * Creates `/home` on the local filesystem
     * Load the class **pam::access**
       * Sets a list of users that are allowed onto the system
     * Load the class **ssh**
       * Sets up `/etc/ssh/sshd_config`
       * Opens port 22 in the firewall
       * Loads the class **ssh::denyhosts**
         * Blocks attempts to brute-force SSH access
     * Load the class **dircolors**
       * Makes `ls` output look pretty for root
   * Load the class **ldap::client**
     * Installs OpenLDAP
     * Sets up NCI LDAP credentials
     * Load the class **nci::nfsh**
       * Installs the script that lets you choose your NCI project on login
   * Load the class **nci::sudo**
     * Grants sudo access to OpenStack tenant members

You can see the Puppet commands that each class executes by going to:

 * Classes starting with **bundle::** are under `modules/bundle/manifests`
 * Other classes are under `corefw/$MODULE/manifests`, with $MODULE replaced by the first section of the class name

## Customizing the Configuration

Puppet gets its default configuration settings through a system called [Hiera](http://docs.puppetlabs.com/hiera/1/). Hiera allows you to create a hierarchy of configuration files based on different facts about the server that it will combine intelligently.

For instance the hierarchy:
[{
#!yaml
  - hieradata/%{::hostname}
  - hieradata/common

will first search for settings in hieradata/$HOSTNAME.yaml, then if it cannot find them there it will look in hieradata/common.yaml (the %{::foo} syntax in Hiera configuration files will be replaced with the output of the command facter foo on the VM).

The NCI bundle uses the following hierarchy:

#!yaml
  - private/hieradata/node/%{::fqdn}
  - hieradata/node/%{::fqdn}
  - private/hieradata/node/%{::hostname}
  - hieradata/node/%{::hostname}
  - private/hieradata/project
  - hieradata/project
  - corefw/hieradata/global

The configuration files use YAML syntax

Firewall rules

By default the firewall will:

• Allow ICMP (ping) connections
• Allow any internal loopback connections
• Allow connections on port 22 (SSH)
• Block connections to the OpenStack metadata service from users other than root
• Block any other connections

Additional firewall rules (e.g. opening up port 80 for websites) can be set using the puppetlabs/firewall module.

NFS mounts

The bundle system supports mounting /home from NFS. To do this add the mount path in your Hiera config, e.g.:

#!yaml
nci::dirs::home::device: 'os-home.nci.org.au:/ab1/home'

Shell Access

To allow users onto the system you must specify them using Hiera. Groups should be specified using parentheses:

#!yaml
# List of users and groups allowed onto the system:
pam::access::allowed_array:
  - 'abc123'
  - 'def456'
  - '(a01)'

# List of users and groups not allowed onto the system:
pam::access::denied_array:
  - 'ghi789'
  - '(b23)'

# Allow anyone to log onto the system:
pam::access:default: 'allow'

# Only allow listed users to log onto the system:
pam::access:default: 'deny'

Sudo Access

To grant Sudo access to a user in Hiera:

#!yaml
nci::sudo::user_specs_hash:
  'sudo for abc123':
      user_list: 'abc123'
      run_as: 'root'
      cmd_list: 'ALL'

Adding new modules

A large number of modules for different projects are available at the Puppet Forge, including a number of important modules supported by the puppet developers for programs like Apache and Postgresql.

To install a module from the Puppet Forge:

puppet module install --target-dir modules puppetlabs/apache

Refer to the documentation of individual modules for how to configure them, generally you'll want to include the module in manifests/nodes.pp, e.g.

node default {
  include bundle::role::default
  include apache
}