Getting started

• Creating Basic Objects
• Investigating Nodes
• Browsing Other Objects

---

This page explains the most important commands for getting started. We assume that you have a Razor server up and running. If not, go to Installation).

Note: When you run Razor commands, you might get this warning: "MultiJson is using the default adapter (ok_json). We recommend loading a different JSON library to improve performance."

This situation is completely harmless. However, if you are using Ruby 1.8.7, you can install a separate JSON library (such as gem install json_pure) to make the warning go away.

Installing the Command Line Client

The command line client is a small utility that makes interacting with the Razor server's REST API more convenient. Because the server and the client only communicate over HTTP, there is no need to run the client on the same machine as the server; in fact, running the client locally is generally preferable.

The client requires that a version of Ruby compatible with Ruby 1.9.3 is installed. Unlike the Razor server, the client doesn't have to run under jRuby. Using a Ruby interpreter with a faster startup time, like MRI Ruby, is usually more convenient.

The client is distributed as a gem and can be installed with this command:

gem install razor-client

You can point the client at the Razor server in two ways, both of which list all the nodes on the server http://razor:8080/api. You can specify the server's API URL with the --url option:

razor --url http://razor:8080/api nodes

Or you can set the RAZOR_API environment variable:

RAZOR_API=http://razor:8080/api razor nodes

## Creating Basic Objects

To use Razor, you need to create repos, brokers, and policies on the server.

Create Repo

Start by loading at least one repo into the server:

razor create-repo --name=centos-6.4 --iso-url http://some.where/centos.iso

All the objects you use with Razor are identified by a name, which has to be unique (i.e., there can only be one repo called 'sles-11') The repo contains the actual bits that are used when installing a node; the installation instructions are contained in tasks. Razor comes with a few predefined tasks to get you started. They can be found in the tasks/ directory in the razor-server repo, and can all be used by simply mentioning their name in a policy. This is described below, and includes the vmware_esxi installer; the one exception to this is the Windows installer, which requires additional preparation.

Create Broker

Besides repos and tasks, you'll also need a broker; brokers are responsible for handing a node off to a config management system, usually Puppet. The following sets up a simple noop broker that does nothing:

razor create-broker --name=noop --broker-type=noop

Create Policy

After a broker is set up, you can create a policy. Policies tie all the other bits and pieces in Razor together, and are ultimately applied to a host. Since a command line to create a policy would be quite a mouthful, store the policy in a JSON file, something like policy.json:

{
  "name": "centos-for-small",
  "repo": { "name": "centos-6.4" },
  "task": { "name": "centos" },
  "broker": { "name": "noop" },
  "enabled": true,
  "hostname": "host${id}.example.com",
  "root_password": "secret",
  "max_count": "20",
  "rule_number": "100",
  "tags": [{ "name": "small", "rule": ["<=", ["num", ["fact", "processorcount"]], 2]}]
}

Then, create the policy on the server:

razor create-policy --json policy.json

With this example policy, the first 20 nodes that have no more than two processors that boot will get the centos-for-small policy applied to them.

## Investigating What's on Your Server

Running razor nodes will produce a list of all the nodes that the Razor server knows about. The list looks something like this:

    id: "http://razor:8080/api/collections/nodes/node42"
  name: "node42"
  spec: "http://api.puppetlabs.com/razor/v1/collections/nodes/member"

... more nodes ...

The name of the node is generated by the server and follows the pattern nodeNNN where NNN is an integer. You can use the name with the razor nodes command to get more information about the node, like this: razor nodes node42.

             id: "http://razor:8080/api/collections/nodes/node42"
           name: "node42"
           spec: "http://api.puppetlabs.com/razor/v1/collections/nodes/member"
        hw_info:
                  mac: ["01-52-54-00-0d-97-f0"]
                 uuid: "ea7c46f8-615f-234f-c1a4-20f0d3edac3d"

       dhcp_mac: "01-52-54-00-0d-97-f0"
         policy: ...
            log:
                 log => http://razor:8080/api/collections/nodes/node42/log
          facts:
                             architecture: "x86_64"
                     blockdevice_vda_size: 4294967296
                   blockdevice_vda_vendor: "0x1af4"
...

It is possible to navigate further into related objects, for example, razor nodes node42 log displays the log of that node:

  timestamp: "2013-11-21T16:49:11+01:00"
      event: "boot"
  installer: "microkernel"
   template: "boot"
       repo: "microkernel"
   severity: "info"

  timestamp: "2013-11-21T16:49:45+01:00"
      event: "bind"
     policy: "centos6"
   severity: "info"

  timestamp: "2013-11-21T16:49:45+01:00"
     action: "reboot"
     policy: "centos6"
   severity: "info"

  timestamp: "2013-11-21T16:50:16+01:00"
      event: "unbind"
     policy: "centos6"
   severity: "info"

## Browsing Other Objects

For any of the collections that Razor supports, you can use razor <collection> to get a list of a specific collection, and razor <collection name> to get the details of an object in that collection. Running razor -h will list all the collections the server knows about.

For example, razor tags lists all tags, and razor tags test shows the details of the tag with name test.