6.3. Configuration

The following JSON is an examples of the current defaults:

config.json

{
    "amqp": "amqp://localhost",
    "rackhdPublicIp": null,
    "apiServerAddress": "172.31.128.1",
    "apiServerPort": 9080,
    "dhcpPollerActive": false,
    "dhcpGateway": "172.31.128.1",
    "dhcpProxyBindAddress": "172.31.128.1",
    "dhcpProxyBindPort": 4011,
    "dhcpSubnetMask": "255.255.240.0",
    "gatewayaddr": "172.31.128.1",
    "trustedProxy": false,
    "httpEndpoints": [
        {
            "address": "0.0.0.0",
            "port": 8080,
            "httpsEnabled": false,
            "proxiesEnabled": true,
            "authEnabled": false,
            "routers": "northbound-api-router"
        },
        {
            "address": "172.31.128.1",
            "port": 9080,
            "httpsEnabled": false,
            "proxiesEnabled": true,
            "authEnabled": false,
            "routers": "southbound-api-router"
        }
    ],
    "httpDocsRoot": "./build/apidoc",
    "httpFileServiceRoot": "./static/files",
    "httpFileServiceType": "FileSystem",
    "fileServerAddress": "172.31.128.2",
    "fileServerPort": 3000,
    "fileServerPath": "/",
    "httpProxies": [
        {
            "localPath": "/coreos",
            "server": "http://stable.release.core-os.net",
            "remotePath": "/amd64-usr/current/"
        }
    ],
    "httpStaticRoot": "/opt/monorail/static/http",
    "authTokenSecret": "RackHDRocks!",
    "authTokenExpireIn": 86400,
    "mongo": "mongodb://localhost/pxe",
    "sharedKey": "qxfO2D3tIJsZACu7UA6Fbw0avowo8r79ALzn+WeuC8M=",
    "statsd": "127.0.0.1:8125",
    "syslogBindAddress": "172.31.128.1",
    "syslogBindPort": 514,
    "tftpBindAddress": "172.31.128.1",
    "tftpBindPort": 69,
    "tftpRoot": "./static/tftp",
    "minLogLevel": 2,
    "logColorEnable": false,
    "enableUPnP": true,
    "ssdpBindAddress": "0.0.0.0",
    "heartbeatIntervalSec": 10,
    "wssBindAddress": "0.0.0.0",
    "wssBindPort": 9100
}

6.3.1. Configuration Parameters

The following table describes the configuration parameters in config.json:

The log levels for filtering are defined at https://github.com/RackHD/on-core/blob/master/lib/common/constants.js#L36-L44

These configurations can also be overridden by setting environment variables in the process that’s running each application, or on the command line when running node directly. For example, to override the value of amqp for the configuration, you could use:

export amqp=amqp://another_host:5763

prior to running the relevant application.

6.3.2. HTTPS/TLS Configuration

To use TLS, a private RSA key and X.509 certificate must be provided. On Ubuntu and Mac OS X, the openssl command line tool can be used to generate keys and certificates.

For internal development purposes, a self-signed certificate can be used. When using a self-signed certificate, clients must manually include a rule to trust the certificate’s authenticity.

By default, the application uses a self-signed certificate issued by Monorail which requires no configuration. Custom certificates can also be used with some configuration.

Parameters

See the table in Configuration Parameters for information about HTTP/HTTPS configuration parameters. These parameters beging with HTTP and HTTPS.

6.3.3. BMC Username and Password Configuration

A node gets discovered and the BMC IPMI comes up with a default username/password. User can automatically set IPMI OBM settings using a default user name(‘__rackhd__’) and an auto generated password in rackHD by adding the following to RackHD config.json:

"autoCreateObm": "true"

If a user wants to change the BMC credentials later in time, when the node has been already discovered and database updated, a separate workflow located at on-taskgraph/lib/graphs/bootstrap-bmc-credentials-setup-graph.js can be posted using Postman or Curl command.

add the below content in the json body for payload (example node identifier and username, password shown below)

{
    "name": "Graph.Bootstrap.With.BMC.Credentials.Setup",
    "options": {
         "defaults": {
             "graphOptions": {
                 "target": "56e967f5b7a4085407da7898",
                 "generate-pass": {
                     "user": "7",
                     "password": "7"
                 }
             },
             "nodeId": "56e967f5b7a4085407da7898"
         }
     }
}

By running this workflow, a boot-graph runs to bootstrap an ubuntu image on the node again and set-bmc-credentials-graph runs the required tasks to update the BMC credentials. Below is a snippet of the ‘Bootstrap-And-Set-Credentials graph’, when the graph is posted the node reboots and starts the discovery process

 module.exports = {
   friendlyName: 'Bootstrap And Set Credentials',
   injectableName: 'Graph.Bootstrap.With.BMC.Credentials.Setup',
   options: {
       defaults: {
           graphOptions: {
               target: null
           },
           nodeId: null
       }
   },
   tasks: [
       {
           label: 'boot-graph',
           taskDefinition: {
               friendlyName: 'Boot Graph',
               injectableName: 'Task.Graph.Run.Boot',
               implementsTask: 'Task.Base.Graph.Run',
               options: {
                   graphName: 'Graph.BootstrapUbuntu',
                   defaults : {
                       graphOptions: {   }
                   }
               },
               properties: {}
           }
       },
       {
           label: 'set-bmc-credentials-graph',
           taskDefinition: {
               friendlyName: 'Run BMC Credential Graph',
               injectableName: 'Task.Graph.Run.Bmc',
               implementsTask: 'Task.Base.Graph.Run',
               options: {
                   graphName: 'Graph.Set.Bmc.Credentials',
                   defaults : {
                       graphOptions: {   }
                   }
               },
               properties: {}
           },
           waitOn: {
               'boot-graph': 'finished'
           }
       },
       {
           label: 'finish-bootstrap-trigger',
           taskName: 'Task.Trigger.Send.Finish',
           waitOn: {
               'set-bmc-credentials-graph': 'finished'
           }
       }
   ]
};

To remove the BMC credentials, User can run the following workflow located at on-taskgraph/lib/graphs/bootstrap-bmc-credentials-remove-graph.js and can be posted using Postman or Curl command.

add the below content in the json body for payload (example node identifier and username, password shown below)

{
    "name": "Graph.Bootstrap.With.BMC.Credentials.Remove",
    "options": {
         "defaults": {
             "graphOptions": {
                 "target": "56e967f5b7a4085407da7898",
                 "remove-bmc-credentials": {
                     "users": ["7","8"]
                 }
             },
             "nodeId": "56e967f5b7a4085407da7898"
         }
     }
}

6.3.4. Certificates

This section describes how to generate and install a self-signed certificate to use for testing.

6.3.4.1. Generating Self-Signed Certificates

If you already have a key and certificate, skip down to the Installing Certificates section.

First, generate a new RSA key:

openssl genrsa -out privkey.pem 2048

The file is output to privkey.pem. Keep this private key secret. If it is compromised, any corresponding certificate should be considered invalid.

The next step is to generate a self-signed certificate using the private key:

openssl req -new -x509 -key privkey.pem -out cacert.pem -days 9999

The days value is the number of days until the certificate expires.

When you run this command, OpenSSL prompts you for some metadata to associate with the new certificate. The generated certificate contains the corresponding public key.

6.3.4.2. Installing Certificates

Once you have your private key and certificate, you’ll need to let the application know where to find them. It is suggested that you move them into the /opt/monorail/data folder.

mv privkey.pem /opt/monorail/data/mykey.pem
mv cacert.pem /opt/monorail/data/mycert.pem

Then configure the paths by editing httpsCert and httpKey in /opt/monorail/config.json. (See the Configuration Parameters section above).

If using a self-signed certificate, add a security exception to your client of choice. Verify the certificate by restarting on-http and visiting https://<host>/api/current/versions.

Note: For information about OpenSSL, see the OpenSSL documentation.

6.3.5. Setup HTTP/HTTPS endpoint

This section describes how to setup HTTP/HTTPS endpoints in RackHD. An endpoint is an instance of HTTP or HTTPS server that serves a group of APIs. Users can choose to enable authentication or enable HTTPS for each endpoint.

There are currently two API groups defined in RackHD:

  • the northbound-api-router API group. This is the API group that is used by users
  • the southbound-api-router API group. This is the API group that is used by nodes interacting with the system
[
    {
        "address": "0.0.0.0",
        "port": 8443,
        "httpsEnabled": true,
        "httpsCert": "data/dev-cert.pem",
        "httpsKey": "data/dev-key.pem",
        "httpsPfx": null,
        "proxiesEnabled": false,
        "authEnabled": false,
        "routers": "northbound-api-router"
    },
    {
        "address": "172.31.128.1",
        "port": 9080,
        "httpsEnabled": false,
        "proxiesEnabled": true,
        "authEnabled": false,
        "routers": "southbound-api-router"
    }
]
Parameter Description
address IP/Interface to bind to for HTTP. Typically this is ‘0.0.0.0’
port Local port to use for HTTP. Typically, port 80 for HTTP, 443 for HTTPS
httpsEnabled Toggle HTTPS
httpsCert Filename of the X.509 certificate to use for TLS. Expected format is PEM. This is optional and only takes effect when the httpsEnabled flag is set to true
httpsKey Filename of the RSA private key to use for TLS. Expected format is PEM. This is optional and only takes effect when the httpsEnabled flag is set to true
httpsPfx Pfx file containing the SSL cert and private key (only needed if the key and cert are omitted) This is optional and only takes effect when the httpsEnabled flag is set to true
proxiesEnabled A boolean value to toggle httpProxies (defaults to false)
authEnabled Toggle API Authentication
routers A single router name or a list of router names. This would only take effect for 1.1 APIs. You can now choose from “northbound-api-router”,”southbound-api-router” or [“northbound-api-router”, “southbound-api-router”].