Installation Guide

This guide describes how to install orcharhino using the “Kickstart + orcharhino installer” method. In other words, we will use a Kickstart file (provided by ATIX) to install CentOS on the host orcharhino will run on. Afterwards we will use the orcharhino installer to install orcharhino itself.

Note

orcharhino is available through a subscription model. Please contact us about getting access.

The installation guide contains the following subsections:

Prerequisites and System Requirements

Note

We recommend installing orcharhino on a virtual server. (Amongst other advantages this will allow for snapshot creation for backups). However, orcharhino can also be installed on a bare metal system.

In order to follow the installation process from this guide, you will require the following:

  • The host orcharhino will run on (see the table below for system requirements).

  • A CentOS installation media.

    Note

    CentOS ISO images can be obtained here: https://www.centos.org/download/

  • The Kickstart file (provided by ATIX) used to install CentOS on the host orcharhino will run on.

  • An orcharhino activation key (provided by ATIX) used to register the orcharhino host.

  • A browser (possibly on some secondary device able to resolve a route to the orcharhino host).

  • A working internet connection.

Regardless of whether it is virtual or bare metal, the system orcharhino will run on, must meet the following requirements:

  Minimal Recommended
Operating System CentOS 7 (as provided by the ATIX Kickstart file)
CPU 4 8
RAM 12 GB 32 GB
HDD 1 (/) 30 GB 50 GB
HDD 2 (/var)

~ 40 GB for each CentOS/RHEL distribution

~ 80 GB for each Debian distribution

~ 500 GB (or as appropriate) if you plan to maintain additional repositories or keep multiple versions of packages

Important

The above system requirements explicitly call for two hard drives. One hard drive will be used for the root partition, and the other for the data repositories. This separation is essential for the creation of snapshots and backups, and the Kickstart files provided by ATIX will not work with a single drive system.

Warning

It is worth allocating sufficient hard drive resources from the outset. Running out of space for your data repositories during regular orcharhino usage can lead to significant pain.

The following ports have to be open to operate orcharhino on your network (at least if you intend to use the corresponding service):

Port Protocol Required for
53 TCP / UDP DNS server
67,68 UDP DHCP server
69 UDP TFTP server
80 TCP Web server
3000 TCP Web application server (internal)
3306 TCP MySQL database server
443 TCP HTTPS Web server
5910- 5930 TCP VNC server
5432 TCP PostgreSQL database server
8140 TCP Puppet server
8443 TCP Smart proxy server
8000 TCP Unattended host provisioning
8015 TCP Only during the installation

Installation Steps

This subsection of the Installation Guide provides step-by-step instructions on all the steps needed to install orcharhino (as well as the CentOS operating system it will run on). In particular, the process involves installing CentOS via a Kickstart file, launching the installation via the install_orcharhino.sh script, and finally configuring your orcharhino using the web interface of the orcharhino installer.

Using the Kickstart File

This subsubsection of the Installation Guide provides step-by-step instructions on using the Kickstart file (provided by ATIX) to install CentOS on the host orcharhino will run on.

Note

ATIX maintains two different Kickstart files depending on what hard drives you are using:

  • orcharhino-wi-el7-sdX.ks to install CentOS on a host with SATA disks (/dev/sdX)
  • orcharhino-wi-el7-vdX.ks to install CentOS on a host with VirtIO disks (/dev/vdX)
  1. Either virtually mount your CentOS installation media or place it’s physical equivalent in the DVD tray for a bare metal install.

  2. Reboot your system using the installation media. Immediately halt the boot process by hitting tab, and append the following boot option:

    ks=http://<path_to_kickstart_file>
    
  3. Hit enter, and the automatic Kickstart installation will now start. It may prompt you to hit enter from time to time.

  4. Once the Kickstart installation has successfully completed, continue with Launching the Installation below.

Launching the Installation

This subsubsection of the Installation Guide provides usage instructions for the initial install_orcharhino.sh script. The purpose of this script is to register your orcharhino host with ATIX to provide it with the needed orcharhino package repositories. Once successfully registered, the script will also install and launch the main orcharhino installer.

The Kickstart installation from the previous subsubsection will have placed the install_orcharhino.sh script in the /root/ folder on your orcharhino host. Alternatively, it is also available for download from ATIX.

Note

The install_orcharhino.sh script supports multiple options, and requires your orcharhino activation key. For a full list of options and usage instructions, run ./install_orcharhino.sh --help.

It is highly recommended to use the --name option to provide your orcharhino with a FQDN/hostname at this point. To do so launch your script as follows:

/root/install_orcharhino.sh --name='orcharhino.example.domain' <or_activation_key>

The install_orcharhino.sh script will prompt you to confirm the settings you are using for your ACC registration as follows:

install_orcharhino.sh: You are about to register to ACC using the following settings:
install_orcharhino.sh:   orcharhino activation key: '<or_activation_key>'
install_orcharhino.sh:   orcharhino FQDN: 'orcharhino.example.domain'
install_orcharhino.sh:   orcharhino IP address: '<or_ip_address>'
install_orcharhino.sh: Proceed with these settings? [Yes/No]

Entering anything other than Yes, yes, Y, or y will cause the script to exit without taking any further actions. You can always rerun the script with modified options. You can override the <or_ip_address> setting using the -i/--ip-addr=ADDR option. You can also skip the above confirmation prompt by using the -y/--yes option.

Once you have confirmed the prompt, the install_orcharhino.sh script will automatically install and launch the main orcharhino installer which will display a link to the web interface. It may take some time to reach this point. The link will look something like the following:

http://192.168.121.179:8015/?token=4f27b9328cc0ead7d499c93f34ec9bda5d26e7b50c4420dc0a80dcc04adcf9dd

Point your browser at the provided link and continue with the following subsubsection.

Using the Web Interface

This subsubsection of the Installation Guide provides step-by-step instructions on using the web interface of the orcharhino installer to configure your install time options.


When you enter the link from the previous step in your browser of choice, you will be greeted by the basic configuration page of the installer (the first of several steps):

Basic configuration
  1. Enter the password for the administrator (admin) account of your orcharhino installation into the fields provided (1).

  2. Enter an email where the orcharhino administrator can be reached into the Admin email field (2).

  3. Finally enter the context that will be used for the initial configuration of your orcharhino host into the Organization and Location fields (3).

    Warning

    Setting an Organization or Location that contains white space or non ascii characters has been known to cause bugs. Please choose a single word that does not include umlauts or special characters.

  4. Hit the Next button (4) once you are done.


The http proxy page will now appear:

HTTP Proxy configuration
  1. If your organization does not use an HTTP proxy server, ignore this step. Otherwise, select the Use HTTP Proxy check mark (1), and fill in your HTTP proxy’s data in the fields provided (2) to (5).
  2. Hit the Next button (6) once you are done.

The networking capabilities page will now appear:

Filled network capabilities
  1. We recommend allowing orcharhino to manage DHCP, DNS, and TFTP on the subnet where it will manage hosts. (Follow all of the steps below for this setup). However, if there is good reason not to do so on your organizations infrastructure, then deselect the corresponding services (1), (6), and/or (11) (and disregard the corresponding steps below).

  2. Configure orcharhino’s DHCP capability.

    1. For the DHCP interface field (2), select the interface to the network on which orcharhino will be deploying hosts. (We will refer to this network as the internal network hence forth).

      Note

      The orcharhino installer will try to guess sensible values for the input fields (3), (4), and (5) based on your DHCP interface selection. We highly recommend double checking these auto-generated values before continuing.

    2. For the DHCP gateway IP field (3), enter the gateway IP address that hosts managed by orcharhino will use (on the internal network). (The auto-generated value will be the default-gateway on the selected interface.)

    3. For the DHCP nameservers field (4), enter the IP address that hosts managed by orcharhino will use to resolve DNS queries. (If Manage DNS (6) is selected this will be the IP address of the orcharhino host on the internal interface, this is also the auto-generated value).

    4. For the DHCP range field (5), enter the range of IP addresses that is available for hosts managed by orcharhino, on the internal network. (The installer will try to calculate the largest free range within the IP network, by excluding its own address, as well as those of the gateway and the configured name server. It is not verified automatically, whether any other hosts already exist within this range.)

  3. Configure orcharhino’s DNS capability.

    1. For the DNS interface field (7), select the interface to the internal network. The same interface you used for the DHCP interface field (2).

      Note

      The orcharhino installer will try to guess sensible values for the input fields (8) and (9) based on your DNS interface selection and the systems resolv.conf file. We highly recommend double checking these auto-generated values before continuing.

    2. For the DNS forwarders field (8), enter the IP address of your organizations DNS server, (or of some external DNS server, that can be reached from the orcharhino host). (The installer tries to pre-fill this field with a DNS server from the system’s resolv.conf file.)

    3. For the DNS reverse field (9), enter the net ID part of the IP address of the internal network in decimal notation, with the byte groups in reverse order, followed by .in-addr-arpa. (For example, a network address of 192.168.0.0/24 would turn into 0.168.192.in-addr-arpa; pre-filled with the appropriate value for the chosen interface).

    4. For the DNS TTL (Time to Live) in sec field (10) enter the desired value.

  4. Select/deselect orcharhino’s TFTP capability (11).

  5. Hit the Next button (12) once you are done.


The operating systems page will now appear:

Operating System configuration
  1. Select any operating systems (1) you want your orcharhino to be preconfigured for.
  2. Hit the Next button (2) once you are done.

Important

If you want to be able to deploy SUSE Linux Enterprise Server (SLES) hosts with your orcharhino, you will need to perform additional steps at the end of the installation process to set up your SLES installation media.


The configuration management page will now appear:

Configuration management selection
  1. Puppet support (1) is a required orcharhino dependency and is always selected.
  2. If you also want Ansible support select the relevant check box (2).
  3. If you also want Salt support select the relevant check box (3).
  4. Hit the Next button (4) once you are done.

The compute resources page will now appear:

Compute resource selection

Warning

The Proxmox compute resource plugin is incompatible with other compute resource plugins. Please choose either Proxmox or one or more other compute resources.

  1. Select any Compute Resource Plugins (1), if you want orcharhino to support those compute resources.
  2. Hit the Next button (2) once you are done.

The plugins page will now appear:

Plugins selection
  1. Select any Plugins (1) you want installed on your orcharhino. (See Plugin Guides for more information).
  2. You can go over your configuration by selecting the Previous button (2).
  3. Hit the Finnish button (3) once you are done. This will trigger the installation process (which will display console output in the browser window, and may take some time).

Once orcharhino has successfully installed, the installer will display something similar to the following:

Web installer finish
  • Click the button provided (1) to go to orcharhino’s login page.
  • Log in using the admin user, along with the password you set via the web interface.
  • Enjoy your brand new orcharhino installation!

Setting up SLES Media

Note

This section presumes you have selected at least one SLES variant from the list of operating systems in the orcharhino installer above. If you did not select an entry like “SUSE Linux Enterprise Server <version>” from the list of operating systems, ignore this section.

The installation media for SUSE Linux Enterprise Servers (SLES) are not generally available by public mirror. (Instead, SLES ISO files can be obtained from SUSE). As a result, it is necessary to add any SLES media you might need to your orcharhino manually. (You will not be able to deploy any SLES hosts out of the box). This section will describe how to add SLES media. This section assumes you have access to any relevant SLES media in the form of ISO files.

If you navigate to the installation media page in the interface of your newly installed orcharhino, you will find that the entries for your SLES media are already created:

SLES installation media

However, the paths displayed for your SLES media are currently pointing at non existent locations. What we need to do, is to unpack our SLES ISO files, to the location specified by these paths. The following step-by-step instructions will illustrate the process for the SLES 11 medium (the process for other SLES versions is analogous, all commands are run as root on the orcharhino host).

  1. Make sure your SLES ISO file is present on your orcharhino host. (How best to move files to your orcharhino host is dependent on your exact setup).

  2. Create the directory for your SLES medium:

    mkdir -p /var/www/html/pub/installation_media/sles/11sp4/
    
  3. Extract your SLES ISO to the newly created directory.

    1. Install p7zip for ISO extraction:

      yum install p7zip p7zip-plugins
      
    2. Perform the extraction:

      7z x <path_to_sles_iso> -o'/var/www/html/pub/installation_media/sles/11sp4/'
      
    3. Make sure the permissions on your extracted files will allow Apache to read them:

      chmod -R go+X+r /var/www/html/pub/installation_media/sles/11sp4/*
      
  4. (optional) Make sure your extracted files are visible (in a browser) at the following location:

    http://<orcharhino-host>.<domain>/pub/installation_media/sles/11sp4/
    
  5. (optional) Remove the SLES ISO file from your orcharhino host (only the extracted files are needed).

Note

Alternatively, you can also host your SLES ISO file on some arbitrary web server, reachable from your orcharhino host (the ISO file needs to be extracted on the web server). Then, simply change the link of the SLES medium’s orcharhino entry, to point at your web server location.