Production Install¶
This document describes the production installation process that is encapsulated by the install.sh script.
TL;DR - From linux prompt as root
The following steps are roughly followed to install DRP.
Getting install.sh¶
The install.sh script drives the entire DRP installation process. It
is available at get.rebar.digital/stable.
Download and inspect before running¶
If you prefer to review the script before executing it:
Use the --drp-version flag to install a specific release,
e.g. --drp-version=v4.6.4.
Run bash install.sh --help for the full list of options.
Offline / Air-gap Install¶
For systems without direct internet access, download the install.sh
script and the DRP archive on a connected machine, transfer both to the
target system, then install using the --zipfile option.
The DRP archive releases are available from the catalog at repo.rackn.io. There are at least 3 release channels to choose from:
- stable - The most recent stable release (recommended).
- tip - The latest master build. Bleeding edge; may have issues.
- v4.6.4 - A specific semantic version. Check the catalog for available versions.
Download the archive and verify its checksum:
export DRPVERSION="v4.6.4" # replace with target version
curl -fsSL https://rebar-catalog.s3-us-west-2.amazonaws.com/drp/$DRPVERSION.zip -o dr-provision.zip
curl -fsSL https://rebar-catalog.s3-us-west-2.amazonaws.com/drp/$DRPVERSION.sha256 -o dr-provision.sha256
sha256sum -c dr-provision.sha256
After transferring both install.sh and dr-provision.zip to the
target system, run:
Note
Previous releases remain available in tag/release history. For additional information, see Release Process.
Install Configuration Options¶
Using dr-provision --help will provide the most complete list of
configuration options. The following common items are provided for
reference. Please note these may change from version to version,
check the current scripts options with the --help flag to verify
current options.
Text Only--version Print Version and exit --disable-provisioner Disable provisioner --disable-dhcp Disable DHCP --static-port= Port the static HTTP file server should listen on (default: 8091) --tftp-port= Port for the TFTP server to listen on (default: 69) --api-port= Port for the API server to listen on (default: 8092) --dhcp-port= Port for the DHCP server to listen on (default: 67) --backend= Storage backend to use. Can be either 'consul' or 'directory' (default: directory) --data-root= Location we should store runtime information in (default: /var/lib/dr-provision) --static-ip= IP address to advertise for the static HTTP file server (default: 192.168.124.11) --file-root= Root of filesystem we should manage (default: /var/lib/tftpboot) --dhcp-ifs= Comma-separated list of interfaces to listen for DHCP packets --debug-bootenv= Debug level for the BootEnv System - 0 = off, 1 = info, 2 = debug (default: 0) --debug-dhcp= Debug level for the DHCP Server - 0 = off, 1 = info, 2 = debug (default: 0) --debug-renderer= Debug level for the Template Renderer - 0 = off, 1 = info, 2 = debug (default: 0) --tls-key= The TLS Key File (default: server.key) --tls-cert= The TLS Cert File (default: server.crt) --systemd= Run the systemd enabling commands after installation --startup= Attempt to start the dr-provision service
Running The Server¶
The install.sh script provides three options for running dr-provision.
- Production mode installations via systemd (this guide)
- isolated for a developer running DRP interactively
- container for trial users minimizing their install requirements
The default values install the server and cli in /usr/local/bin. It will also put a service control file in place. Once that finishes, the appropriate service start method will run the daemon. The install.sh script prints out the command to run and enable the service.
Note
The default location for storing runtime information is
/var/lib/dr-provision unless overridden by --data-root
The default username & password used for administering the dr-provision service is:
Please review --help for options like disabling services,
logging or paths.
Note
sudo may be required to handle binding to the TFTP and DHCP ports.
Once running, the following endpoints are available:
- https://127.0.0.1:8092/swagger-ui - swagger-ui to explore the API
- https://127.0.0.1:8092/swagger.json - API Swagger JSON file
- https://127.0.0.1:8092/api/v3 - Raw api endpoint
- https://127.0.0.1:8092/ - Redirects to RackN Portal (available for community use)
- http://127.0.0.1:8091 - Static files served by http from the test-data/tftpboot directory
- https://127.0.0.1:8090 - Static files served by https from the test-data/tftpboot directory (4.7 and higher)
- udp 69 - Static files served from the test-data/tftpboot directory through the tftp protocol
- udp 67 - DHCP Server listening socket - will only serve addresses when once configured. By default, silent.
- udp 4011 - BINL Server listening socket - will only serve bootfiles when once configured. By default, silent.
The API, File Server, DHCP, BINL, and TFTP ports can be configured, but DHCP, BINL, and TFTP may not function properly on non-standard ports.
Note
On MAC DARWIN there is one additional step. You may have to add a route for broadcast addresses to work. This can be done with the following command. The 192.168.100.1 is the IP address of the interface that you want to send messages through. The install script will make suggestions for you.
Production Deployments¶
The following items should be considered for production deployments. Recommendations may be missing so an operator should use their best judgement.
Non-root Execution¶
If you are using DHCPD and TFTPD services of DRP, you will need to be able to bind to port 67 and 69 (respectively). Typically Unix/Linux systems require root privileges to do this.
Note
DRP doesn't start as root and then drop privileges with a fork() to
another less privileged user by default.
To enable DRP endpoint to run as a non-privileged user and ensure a higher level of security, it's possible to use the Linux "setcap" (Capabilities) system to assign rights for the dr-provision binary to open low numbered (privileged) ports. The process is relatively simple, but does (clearly/obviously) require root permissions initially to enable the capabilities for the binary. Once the capabilities have been set, the dr-provision binary can be run as a standard user.
To enable any non-privileged user to start up the dr-provision binary and bind to privileged ports 67 and 69, do the following:
production mode
sudo setcap "cap_net_raw,cap_net_bind_service=+ep" /usr/local/bin/dr-provision
isolated mode
sudo setcap "cap_net_raw,cap_net_bind_service=+ep" $HOME/bin/linux/amd64/dr-provision
Start the "dr-provision" binary as an ordinary user, and now it will have permission to bind to privileged ports 67 and 69.
For automated upgrade from within
DRP, the user that is running DRP needs to have the following in
/etc/sudousers. In this example, drp-user is the user
running DRP. This will allow DRP to update itself.
Note
The setcap command must reference the actual binary itself, and can not be pointed at a symbolic link. Additional refinement of the capabilities may be possible. For extremely security conscious setups, you may want to refer to the StackOverflow discussion (eg setting capabilities on a per-user basis, etc.): https://stackoverflow.com/questions/1956732/is-it-possible-to-configure-linux-capabilities-per-user
Note
You must run the setcap command after every upgrade of DRP, the setcap tracks the binary and if it changes, you must rerun for the new binary.
System Logs¶
The Digital Rebar Provision service logs by sending output to standard error. To capture system logs, SystemD (or Docker) should be configured to direct this output to the desired log management infrastructure.
Job Log Rotation¶
If you are using the jobs system, Digital Rebar Provision stores job logs based on the directory configuration of the system. This data is considered compliance related information; consequently, the system does not automatically remove these records.
An Operator should set up a job log rotation mechanism to ensure that these logs to not exhaust available disk space.
Removal of Digital Rebar Provision¶
To remove Digital Rebar Provision, use install.sh to remove programs
for production installs. The script should be run as root or under
sudo unless the setcap process was used.
To remove programs and data use:
Running the RackN UX Locally¶
Setting up DRP to host the RackN UX locally is trivial. The DRP server includes an embedded web server that can host the UX files from a local directory. The RackN UX can also be set up using any other HTTP server, however this document only addresses the setup related to using DRP as the HTTP server.
The RackN UX uses the rackn-license content pack for entitlements so no external login to the RacKN SaaS is required.
The RackN UX will still attempt to connect the RackN SaaS for updates
and the catalog; however, the system will operate even if these calls
fail. This can be turned off by setting the ux.core.airgap option in
the UX Config page to true.
- Air Gap mode - the RackN UX disables all external calls and only operates against the local DRP endpoint.
Setup¶
Before starting, you'll need a copy of the RackN UX and to have
installed a rackn-license.json content package in the DRP server.
These items require a current RackN license - using them without a valid
enterprise or trial license is a copyright violation.
By default, the RackN DRP server will look for the files in a
a directory named ux at the same level as the base-root directory, e.g.
/var/lib/dr-provision. The account running your dr-server must
have read permission for this directory. See below for directions to do this
via the DRPCLI.
This default is NOT recommended or easy to maintain. The install.sh process
will use different values for exposing the UX.
The dr-provision command line options that are needed to server the UX are:
--local-ui- This is a path that can be absolute or relative. It defaults toux, but should not be used. The relative paths are relative to thebase-rootoption. This is usually/var/lib/dr-provision. The install.sh will configure the system to use a value oftftpboot/files/ux. This is the preferred value and understand by other tooling like the CLI and UX. This will specific what is served by tftp, http, and https requests to the/uxdirectory space of the DRP server.--ui-url- This is the URL that the ux directory will be directed to. By default, this will be https://portal.rackn.io. This will need to be changed to/ux. This will cause redirects to the--local-uifiles.
A common systemd file looks like this:
/etc/systemd/system/dr-provision.service.d/local-ui.conf
After the install flags are set, the following steps may be used to upload the local UX to the endpoint. This can be performed remotely.
Install local UX
Running the UX from DRP¶
By unpacking the files in the directory referenced by --local-ui,
the DRP endpoint will serve that directory as /local-ui and /ux.
The endpoint will detect file changes so no restart is required if you update or change the RackN UX files.
If you are using the default port, you will be redirect to the local UX
(served from https://[DRP IP]/ux) instead of the RackN portal when you
open the DRP endpoint in a browser.
Note
This will only serve the files for the UX; it will not ensure that the UX starts connecting to the current DRP instance. To address that, continue below.
Redirecting URL¶
If you are hosting a local UX, you should change the DRP endpoint UX
redirect. This is the site that is presented if you visit the DRP
endpoints root URL, /, or the official UI url, /ui. To use the local
ux, add --ui-url=/ux to the dr-provision command line arguments.
If you have connect to this DRP Endpoint previously, you may need to clear the browsers permanent redirect cache to start using the new feature.