At a minimum, to install Razor, you must install the Razor server.
We also recommend these tasks:
Important: Don’t install the Razor server on your Puppet master.
Tip: Use variables to avoid repeatedly replacing placeholder text. For installation, we recommend declaring a server name and the port to use for Razor with these commands:
export RAZOR_HOSTNAME=<server name> export HTTP_PORT=8150 export HTTPS_PORT=8151
The installation tasks on this page use
$<RAZOR_HOSTNAME>
,$<HTTP_PORT>
and$<HTTPS_PORT>
to represent these variables.
Installing Razor involves classifying a node with the pe_razor
class. When PE applies this classification, the software downloads automatically and installs a Razor server and a PostgreSQL database. The download can take several minutes.
Because the Razor software is stored online, you need an internet connection to install it.
Host your own remote directory containing a PE tarball and the Razor microkernel. This directory is used to install Razor. The directory can be hosted on the Razor server, in which case the URL starts with file://
.
Before you begin: Copy the Razor microkernel and the PE tarball appropriate for your installation to your own FTP site or to the Razor server.
In the pe_razor class, specify the URL for your tarball, then click Add parameter.
Option | Definition |
---|---|
Parameter name | pe_tarball_base_url |
Value | URL for the tarball |
The tarball must retain the same name format as on the Puppet server. The default URL is $<MIRROR>/<PE_BUILD>/puppet-enterprise-<PE_BUILD>-<RELARCH>.tar.gz
, in which $<MIRROR>
represents the address of the base directory.
For example, https://internal.mirror.net/2015.3.3/puppet-enterprise-2015.3.3-el-7-x86_64.tar.gz
.
Note: The pe_tarball_base_url parameter can only be used for installation, not upgrades.
In the pe_razor class, specify the URL for the microkernel, then click Add parameter.
Option | Definition |
---|---|
Parameter name | microkernel_url |
Value | URL for the microkernal. |
The URL is either your FTP site or, if you copied the microkernel to the Razor server, file:///path/to/microkernel.tar
.
Commit your changes.
On the Razor server (the node that you classified with the pe_razor class), run Puppet.
(Optional) Install the Razor client.
From a web-enabled machine, fetch these gems:
/opt/puppetlabs/puppet/bin/gem fetch colored --version 1.2
/opt/puppetlabs/puppet/bin/gem fetch command_line_reporter --version 3.3.6
/opt/puppetlabs/puppet/bin/gem fetch mime-types --version 1.25.1
/opt/puppetlabs/puppet/bin/gem fetch multi_json --version 1.12.1
/opt/puppetlabs/puppet/bin/gem fetch pe-razor-client --version 1.2.0
/opt/puppetlabs/puppet/bin/gem fetch rest-client --version 1.6.9
/opt/puppetlabs/puppet/bin/gem install -f --local *.gem
.The default ports for Razor are port 8150 for HTTP communication between the server and nodes, and port 8151 for HTTPS, used for accessing the public API. You can optionally change the default ports if they’re occupied by another service, out of range, or blocked by a firewall.
pe_razor
class.server_http_port
or server_https_port
.pe_razor
classParameters for the pe_razor
class enable customization of your Razor installation. You can review configuration settings that are currently being used by Razor with the razor config
command.
The pe_razor
class has these parameters:
Parameter | Default | Description |
---|---|---|
api_config_blacklist | [ ‘facts.blacklist’, ‘database_url’] | Properties that Razor hides from query results. You can add additional properties to protect sensitive data. |
auth_config | /etc/puppetlabs/razor-server/shiro.ini | Path to the authentication configuration file. |
auth_enabled | false | true to enable authentication for requests to /api endpoints. |
broker_path | /etc/puppetlabs/razor-server/brokers:brokers | Colon-separated list of directories containing broker types. |
checkin_interval | 15 | Interval, in seconds, at which the microkernel checks in with the Razor server. |
database_url | jdbc:postgresql:razor?user=razor&password=$dbpassword | URL for the Razor server. |
dbpassword | razor | Password to the Razor database. |
facts_blacklist | [‘domain’, ‘filesystems’, ‘fqdn’, ‘hostname’, ‘id’, ‘/kernel.*/’, ‘memoryfree’, ‘memorysize’, ‘memorytotal’, ‘/operatingsystem.*/’, ‘osfamily’, ‘path’, ‘ps’, ‘rubysitedir’, ‘rubyversion’, ‘selinux’, ‘sshdsakey’, ‘/sshfp_[dr]sa/’, ‘sshrsakey’, ‘/swap.*/’, ‘timezone’, ‘/uptime.*/’] | Facts that Razor ignores. Each entry may be a string or a regexp enclosed in /../ where any fact that matches the regexp is dropped. |
facts_match_on | [] | Array of values used to match nodes from within the microkernel to nodes in Razor’s database. By default, this parameter excludes /^macaddress.*/ (regex), serialnumber , and uuid , which are already used. |
hook_execution_path | /opt/puppetlabs/puppet/bin | Colon-separated list of paths that Razor searches in order when running hooks, prior to using the default execution path. |
hook_path | /etc/puppetlabs/razor-server/hooks:hooks | Colon-separated list of directories containing hook types. |
match_nodes_on | [‘mac’] | Array of values used to match nodes when a node PXE boots. Values can include mac , serial , asset , or uuid . |
microkernel_debug_level | quiet | Sets the logging level for the microkernel. Valid values are quiet or debug . |
microkernel_extension_zip | /etc/puppetlabs/razor-server/mk-extension.zip | Zip file that specifies custom facts or other code that is unpacked by the microkernel prior to checkin. |
microkernel_kernel_args | ’’ | Additional command-line arguments that are supplied to the microkernel during boot. |
microkernel_url | https://pm.puppetlabs.com/puppet-enterprise-razor-microkernel-$ |
Location of the Razor microkernel used to install Razor offline. |
pe_tarball_base_url | https://pm.puppetlabs.com/puppet-enterprise | Location of the Puppet Enterprise tarball used to install Razor offline. |
protect_new_nodes | false | true to make new machines ineligible for provisioning. |
repo_store_root | /opt/puppetlabs/server/data/razor-server/repo | Directory where repository contents are downloaded and served. |
secure_api | true | true to require HTTPS/SSL communication with /api endpoints. |
server_http_port | 8150 | Port that nodes use to communicate with the server over HTTP. Only URLs starting with /svc need to be available on this port. |
server_https_port | 8151 | Port that the client uses to communicate with the server’s public API over HTTPS. Only URLs starting with /api need to be available on this port. |
task_path | /etc/puppetlabs/razor-server/tasks:tasks | Colon-separated list of directories containing tasks. |
Use a test command to verify that the Razor server is correctly installed. The output JSON file test.out
contains a list of available Razor commands.
wget https://$<RAZOR_HOSTNAME>:$<HTTPS_PORT>/api -O test.out
.The Razor client is installed as a Ruby gem, pe-razor-client
. The process for installing the client differs by platform.
Note: Don’t install the PE client, pe-razor-client
, alongside the open source Razor client, razor-client
. If you already have razor-client
installed, or are not sure if you do, run gem uninstall razor-client
before installing the PE client.
gem install pe-razor-client
.Point the Razor client to the server: razor -u https://$<RAZOR_HOSTNAME>:$<HTTPS_PORT>/api
.
An error displays if the client isn’t installed or can’t connect to the server.
gem install json_pure
.gem install pe-razor-client
.Set an environment variable for the Razor server URL: setx RAZOR_API https://$<RAZOR_HOSTNAME>:8151/api
.
Tip: Alternatively, you can set the variable through User Accounts in the Control Panel.
Two methods are required to secure your Razor server:
Enable authentication security to control what tasks users can perform. For example, you might limit certain users to read permissions to avoid accidental overwrite of nodes.
Specify Shiro authentication. In the pe_razor
class, modify these settings:
Parameter | Value |
---|---|
auth_enabled |
true |
auth_configured |
Location of the Shiro file, /etc/puppetlabs/razor-server/shiro.ini |
Specify users and roles in your shiro.ini
file, located at /etc/puppetlabs/razor-server/shiro.ini
.
For example, this INI file specifies two users: razor is an admin who can perform all functions, and other is a user who can perform only read operations, such as viewing collections.
[main]
[users]
# define users known to shiro, using the format:
# <username> = <password>, <role>[, <role>...]
razor = razor, admin
other = pass, user
[roles]
# define roles and their associated permissions
admin = *
user = query:*
For more details, see Apache’s guide to INI configuration.
Restart the Razor service: service pe-razor-server restart
.
These are the available permissions for Razor.
Note: Commands have varying access control patterns. Use razor <COMMAND_NAME> --help
to view required permissions for each command.
Task | Permission |
---|---|
Query all collections | query:* |
Query the node collection | query:nodes |
Query a specific node | query:nodes:<NODE_NAME> |
Run all commands | commands:* |
Create policies | commands:create-policy:* |
Create policies starting with a specific name | commands:create-policy:<NAME>* |
Verify your installation by checking the version of the Razor server and client. This information can also be useful for troubleshooting.
razor --version
or razor -v
.