Skip to content
This repository was archived by the owner on Jun 4, 2021. It is now read-only.

Installation

Jump to bottom
smcclellan edited this page Nov 14, 2018 · 91 revisions

This section describes how to get Razor set up and running. Once you've completed these steps, head over to Getting Started to learn how to use the Razor command line.

Note: If you're a Puppet Enterprise user, you should install Razor via the PE tarball. See Install Razor in the Puppet Enterprise documentation for more information.

Database Setup

Razor uses PostgreSQL as its database; you therefore need to have it installed somewhere, e.g. the machine that will be running your Razor server. Once PostgreSQL is up and running, you need to create a database user (createuser -P razor) and a database (createdb -O razor razor_prd)

You should verify that the user who will run the Razor server can connect to the razor database by running psql -l -U razor razor_prd. If this command prints a list of databases including razor_prd, you're done. The troubleshooting section has some tips for how to resolve problems should the above command fail.

The following is an example Puppet manifests installing Postgres using puppetlabs-postgresql module:

class { 'postgresql::globals':
  manage_package_repo => true,
  version             => '9.2',
}->

class { 'postgresql::server': }

postgresql::server::db { 'razor':
  user     => 'razor',
  password => postgresql_password('razor', 'secret'),
}

Razor Server Setup

There are two ways you can set up your server:

In both methods, you'll have to modify config.yaml. The two important configuration settings in config.yaml:

  • The database_url in the production section; set that to something like 'jdbc:postgresql:razor?user=razor&password=secret'.
  • The repo_store_root. This should point to a directory where the Razor server can store OS repos, and should therefore have a good amount of available space and be writable by user razor.

Installing packages

We make releases of Razor available in packages for a variety of operating systems. The packages should be "PC1" packages for either Apt or Yum. For example, for CentOS 7, you'd do the following:

# yum install http://yum.puppetlabs.com/puppetlabs-release-pc1-el-7.noarch.rpm
# yum install razor-server

On Ubuntu Xenial, this would be:

# wget https://apt.puppetlabs.com/puppetlabs-release-pc1-xenial.deb
# dpkg -i puppetlabs-release-pc1-xenial.deb

After installing the razor-server package, you need to edit /etc/puppetlabs/razor-server/config.yaml and at least change the database_url setting. Once that is done, you can load the Razor database schema into your PostgreSQL database, and finally start the service:

# sudo -u razor razor-admin -e production migrate-database
# service razor-server start

razor-admin may not be on the path immediately following installation of the service. To work around this, you can:

  • Run source /etc/profile.d/razorserver.sh first
  • Log out and back in first, or
  • Fully qualify the executable: /opt/puppetlabs/bin/razor-admin

Verify Your Installation

After you've followed one of the above installation methods, you should be able to go to http://localhost:8150/api and get the API entrypoint that will give you a JSON document that talks about collections and commands.

Install the Microkernel

You also need to set up a microkernel. You can download a prebuilt microkernel that has been built using the code in the razor-el-mk and is based on CentOS 7. The microkernel needs to be manually put into your repo_store_root directory and cannot be added using the API. If you downloaded the prebuilt microkernel above, simply extract it into your repo_store_root directory. Doing so will create a subdirectory called microkernel with its contents.

Razor Client Setup

The Razor client is a command line utility that executes commands against the Razor server. To install the client, issue: gem install razor-client. Run the following to get a list of all the collections and commands the server knows about.

razor -u http://razor:8150/api --help

Make sure that the hostname in the URL above is correct and points to where your Razor server is running. If the Razor server is on the same machine as the Razor client, you should be able to omit the -u http://razor:8150/api argument.

The client can be run under MRI Ruby; any 1.8.7+ Ruby should work. Since jruby is quite slow to start up, MRI actually is much more comfortable for the client.

The source for the client lives in a separate repo.

PXE Setup

You must also set your machines to PXE boot. Without PXE booting, Razor has no way to interact with a system. This is OK if the node has already been enrolled with Razor and is installed, but it will prevent any changes on the server (for example, an attempt to reinstall the system) from having any effect on the node. Razor relies on "seeing" when a machine boots and starts all its interactions with a node during a node's boot.

This should be a one-time setup.

Put the following files into your TFTP server's directory (usually /var/lib/tftpboot or /tftpboot):

  • The iPXE undionly.kpxe firmware. There are lots of options for getting your machines to boot iPXE. The ipxe website describes how to do this.
  • Save the Razor iPXE bootstrap script as bootstrap.ipxe. Your server will generate this when you go to http://razor:8150/api/microkernel/bootstrap?nic_max=N. Do not use localhost as the hostname in this URL, as the hostname gets embedded in the bootstrap script, and must be the hostname that your machines will use to reach the server when they boot. The nic_max parameter indicates the maximum number of NICs for which bootstrap.ipxe will report MACs back to the server. It is optional and defaults to 4. This is also the maximum number of NICs on which bootstrap.ipxe will attempt to perform DHCP.

Set your DHCP server to boot machines into undionly.kpxe if they are not using iPXE, and to boot bootstrap.ipxe if they are (you can distinguish them, e.g. using the fact that iPXE sets DHCP option 175).

Using ISC DHCP as Your DHCP Server (recommended)

If you are using a ISC DHCP server as your DHCP server, the following configuration settings can be used to redirect servers to your TFTP server to either get iPXE boot running or directly start the Razor bootstrap if they are already running iPXE:

# This works for ISC DHCP Server 4.1-ESV-R4 (ubuntu 12.04 LTS default)
subnet 192.168.1.0 netmask 255.255.255.0 {
  range 192.168.1.200 192.168.1.250;
  option subnet-mask 255.255.255.0;
  if exists user-class and option user-class = "iPXE" {
    filename "bootstrap.ipxe";
  } else {
    filename "undionly.kpxe";
  }
  next-server 192.168.1.100;
}

Note next-server and subnet IPs have to be adapted to your environment.

Using dnsmasq as Your PXE and TFTP Server

In dnsmasq, set these configurations settings. Note that this works for dnsmasq 2.45. Also, iPXE sets option 175; mark it for network IPXEBOOT.

dhcp-match=IPXEBOOT,175
dhcp-boot=net:IPXEBOOT,bootstrap.ipxe
dhcp-boot=undionly.kpxe
# TFTP setup
enable-tftp
tftp-root=/var/lib/tftpboot

Copy undionly.kpxe and bootstrap.ipxe to /var/lib/tftpboot.

Using Windows DHCP Server

How to setup iPXE on Windows DHCP is explain at http://ipxe.org/howto/msdhcp.

Following changes to work with razor:

Set Option 066 to your tftp-servers hostname, e.g. razor Set Option 066 for iPXE to bootstrap.ipxe (full url not possible).

Using Infoblox for DHCP

The DHCP configuration for Infoblox is as follows:

if (user-class="iPXE") then{
    next-server 10.1.1.1
    bootfile bootstrap.ipxe
}
if (user-class exists AND user-class!="iPXE") then{
    next-server 10.1.1.1
    bootfile undionly.kpxe
}

Using libvirt Machines

To simply try out Razor, virtual machines are perfect. If you're using libvirt, have a look at Running machines in libvirt.

Using Razor without PXE

It is also possible to use Razor without PXE at all; unfortunately, this requires building your own iPXE binaries with Razor's bootstrap.ipxe embedded. The ins and outs are documented on the iPXE website

For example, to generate an ISO that has Razor's bootstrap.ipxe embedded do the following:

curl -o /tmp/bootstrap.ipxe http://razor:8150/api/microkernel/bootstrap
git clone http://git.ipxe.org/ipxe.git
cd ipxe/src
make EMBED=/tmp/bootstrap.ipxe bin/ipxe.iso

You can then use the resulting ISO image to boot machines; you will still need DHCP so that machines have network access, but no TFTP server or any special setup on your DHCP server.

Developer's Setup

If you plan on developing for Razor, use the following from-source method, which will allow you to use a development environment to view code changes.

Installation From Source

Besides the database above, you also need to install these additional tools:

  • Install libarchive. It's used to unpack ISO images that are imported with create-repo. Since we're using this library via FFI, make sure you have the development version installed; on Red Hat distributions (i.e., RHEL/Fedora), you need to install the libarchive-devel package.
  • jRuby 9.1.5.0: we recommend using rbenv to install and manage different Ruby versions on your machine.
  • Bundler: run gem install bundler.
  • Git: we are going to run the server from source.

Run the following commands:

git clone https://github.com/puppetlabs/razor-server.git
cd razor-server
bundle install
cp config.yaml.sample config.yaml
vi config.yaml
# At the very least, change production.database_url and repo_store_root
./bin/razor-admin -e production migrate-database
torquebox deploy --env production
torquebox run --bind-address 0.0.0.0

If your TorqueBox runs, but is not giving any useful answer on requests to the http://localhost:8150/api URL, for example, if you get error 404 Resource not found, stop TorqueBox. Then, redeploy TorqueBox using the --env parameter and give the environment you want to use. After a restart, TorqueBox should answer as expected.

When you want to update the server, simply run git pull and touch $(torquebox env JBOSS_HOME)/deployments/razor-server-knob.yml.deployed.

Upgrading

During an upgrade, the application is not automatically redeployed since database migrations may be necessary. The steps are as follows:

  1. Stop the razor-server service.
  2. Install the new packages.
  3. Perform the razor-admin migrate-database command to ensure the database is up-to-date. You may need to specify the environment in this command, with e.g. -e production. You may also need to log out of the shell and back in to ensure the executable is on the path.
  4. Redeploy the application using these commands:

For upgrading to a razor-server with version > 1.3.0:

    source /etc/puppetlabs/razor-server/razor-torquebox.sh
    torquebox deploy /opt/puppetlabs/server/apps/razor-server/share/razor-server --env=production

For upgrading to a razor-server with version <= 1.3.0:

    source /etc/razor/razor-torquebox.sh
    torquebox deploy /opt/razor --env=production
  1. Start the razor-server service.

Any problems during startup should be logged at /var/log/puppetlabs/razor-server/server.log (> 1.3.0) or /var/log/razor-server/server.log (<= 1.3.0).

Troubleshooting Database Connection Problems

The one thing about PostgreSQL that can be infuriating is getting a connection to the database to work. Here are some helpful hints for troubleshooting database connection problems. They all assume that the database is running on localhost, that the database user is razor, and that the database is called razor_dev. Everything else is an advanced setup.

  1. Your database must be accessible via TCP since the JDBC PostgreSQL driver that Razor uses only supports TCP connections, not Unix domain sockets.

  2. Check that your pg_hba.conf allows connections via TCP for the user and database that you are using. The simplest, and least secure, version is: host all all 127.0.0.1/32 md5. (Note: EL 7

  3. Check that psql can connect to the database by running psql -h 127.0.0.1 -l -U razor; this will print a list of all the databases on your PostgreSQL server.

  4. Check that sequel is happy with your database connection URL: sequel 'jdbc:postgresql:razor?user=razor&password=secret' -c 'puts DB.get{now{}}' will print the current time and date as understood by the database.

  5. Check that the above is the sequel URL for development.database_url in your config.yaml file.

Clone this wiki locally