Skip to main content

Install Chef 360 Platform CLIs

This page explains how to download and install the Chef 360 Platform CLIs and register your computer with Chef 360 Platform. The Chef 360 Platform CLIs let you securely interact with Chef 360 Platform.

Prerequisites

Install CLIs

To download and install the CLIs from your Chef 360 Platform UI, follow these steps:

  1. Log into the Chef 360 Platform web UI and select Download Centre.

  2. On the Chef Platform Bundled Tools page, follow the instructions to download the Chef 360 Platform CLIs that you plan to use. For example, if you only plan to execute Courier jobs, then just install the chef-courier-cli CLI.

  3. Optional: Use the --help flag to verify that you’ve installed the CLIs:

    • chef-courier-cli --help

    • chef-dsm-cli --help

    • chef-platform-auth-cli --help

    • chef-node-management-cli --help

    • hab --help

Install and configure the bash-completion package

Each Chef 360 Platform CLI has a completion bash subcommand. You must install the bash-completion package to run these subcommands.

To install and configure the bash-completion package, follow these steps:

  1. Install the bash-completion package.

    To install the bash-completion package on Linux systems, use the APT or Yum package manager:

    sudo apt-get install bash-completion

    or

    sudo yum install bash-completion

    To install the bash-completion package on macOS, use Homebrew:

    brew install bash-completion

  2. Configure your Bash shell.

    To load the bash-completion package in every shell session by default, you must enable it in the .bash_profile or .bashrc file.

    To enable it on Linux systems, add the following lines to the .bash_profile or .bashrc file:

    if [ -f /etc/bash_completion ] && ! shopt -oq posix; then
    . /etc/bash_completion
fi

    To enable it on macOS, add the following lines to the .bash_profile or .bashrc file:

    if [ -f $(brew --prefix)/etc/bash_completion ]; then
    . $(brew --prefix)/etc/bash_completion
fi

    or

    if [[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]]; then
    . "$(brew --prefix)/etc/profile.d/bash_completion.sh"
fi

Connect to Chef Declarative State Management

If you’re enabling the Chef Declarative State Management (DSM) services, install Chef Workstation and configure knife to connect to Chef DSM.

Prerequisites

Before you begin:

  • The DSM administrator must complete the following tasks:

    • In Organization Management > Users, assign DSM Org Admin privileges to new users.
    • Onboard users into DSM using Invite user for new users, or Retry for users already in the organization.
    • In Tenant Management, confirm the DSM org status is Completed. If it isn’t, select Retry to complete the setup.

  • You must get the following information on the Account Settings page in the Chef 360 Platform web UI:

    • your DSM username
    • your DSM user key: select Regenerate Key and save the downloaded file as a .pem file to ~/.chef/ (Linux and macOS) or %USERPROFILE%\.chef\ (Windows).

Install and configure Chef Workstation

To install Chef Workstation and configure knife to connect to Chef DSM, follow these steps:

  1. Install Chef Workstation locally.

  2. Set up Chef Workstation to connect to Chef DSM.

    In the config.rb or credentials file, use the following settings:

    node_name        "<DSM_USER_NAME>"
client_key       "#{ENV['HOME']}/.chef/<KEY_FILE_NAME>"
chef_server_url  "https://<CHEF_360_FQDN>:31000/organizations/<ORG_NAME>"

    Replace the following:

    • <DSM_USER_NAME> with your DSM user name.
    • <KEY_FILE_NAME> with your PEM key filename.
    • <CHEF_360_FQDN> with your Chef 360 Platform FQDN.
    • <ORG_NAME> with your DSM organization name.

  3. Fetch SSL certificates using the knife ssl fetch command.

    knife ssl fetch

    This copies SSL certificates from an HTTPS server to the $HOME/.chef/trusted_certs directory used by knife and Chef Infra Client.

  4. If Chef 360 Platform authenticates with self-signed certificates, retrieve your root CA certificate with the following command:

    curl -k <TENANT_URL>/platform/system/v1/tenant/root-ca \
  | jq -r '.item.rootCa' \
  | sed 's/\\n/$'\''\n'\''/g' \
  > root-ca.crt

    Replace <TENANT_URL> with your Chef 360 Platform server hostname or IP address.

    Save the CA certificate file locally in $HOME/.chef/trusted_certs.

Get the root certificate

If your Chef 360 Platform deployment is configured with a system-generated or custom certificate, get the root certificate authority (CA) file so you can register your computer with Chef 360 Platform.

  • To get the root certificate file from Chef 360 Platform, run this command:

    curl -k <TENANT_URL>/platform/system/v1/tenant/root-ca \
  | jq -r '.item.rootCa' \
  | sed 's/\\n/$'\''\n'\''/g' \
  > root-ca.crt

    Replace <TENANT_URL> with your Chef 360 Platform server hostname or IP address.

Register your computer with Chef 360 Platform

When you register your computer with Chef 360 Platform, you create a profile that allows you to securely connect to and perform operations with Chef 360 Platform.

A profile defines the following:

You can create multiple profiles with different settings and you can assign one profile as your default profile.

To register your computer with Chef 360 Platform, follow these steps:

  1. Create a profile using the register-device subcommand that associates your computer with a specific tenant, organization, and role:

    chef-platform-auth-cli register-device \
    --device-name <COMPUTER_NAME> \
    --profile-name <PROFILE_NAME> \
    --url <TENANT_URL>

    If you’ve configured Chef 360 Platform with a system-generated or custom certificate in the API/UI settings and you don’t have the root certificate authority, use the --insecure flag. This flag skips certificate validation.

    chef-platform-auth-cli register-device \
    --device-name <COMPUTER_NAME> \
    --profile-name <PROFILE_NAME> \
    --url <TENANT_URL>
    --insecure

    If you’ve configured Chef 360 Platform with a system-generated or custom certificate in the API/UI settings and have the root certificate authority present, use --cafile with the path to the root CA file.

    chef-platform-auth-cli register-device \
    --device-name <COMPUTER_NAME> \
    --profile-name <PROFILE_NAME> \
    --url <TENANT_URL> \
    --cafile <ABSOLUTE_PATH_TO_ROOT_CA_FILE>

    Replace:

    • <COMPUTER_NAME> with a name for your computer.
    • <PROFILE_NAME> with a profile name.
    • <TENANT_URL> with the tenant URL, for example https://chef360.example.com:31000.

    The CLI responds with an authorization code that includes a link to log into Chef 360 Platform.

    Device Id :  ac:de:48:00:11:22-admin-chef-courier-cli
Device Name : <DEVICE_NAME>
OAuth Code : <AUTHORIZATION_CODE>

Please log in and authorize the the device by using the link below:
https://chef360.example.com/platform/user-accounts/v1/identity/device/ac:de:48:00:11:22-admin-chef-courier-cli/authorize?oauthCode=<AUTHORIZATION_CODE>&appType=chef-courier-cli&deviceName=<COMPUTER_NAME>

Is the device authorized? (y or n)

    The CLI waits for the device registration process to finish in the browser.

    Note

    The response includes an access key and secret key. Save these keys. You can use these keys to authenticate with the Chef 360 Platform APIs or to create a JSON Web Token.

  2. Open a browser, navigate to the link returned by the CLI, and log in if you haven’t already.

  3. Select the organization and role you would like to link to this profile and select Submit.

  4. On the Device Authorization screen, Chef 360 Platform shows your OAuth code and you can select an expiration date for your session.

    Chef 360 Platform automatically refreshes your access token up to this expiration date.

    After entering this information, select Authorize.

  5. Return to your terminal and enter y to continue.

    The CLI displays your device profile and your computer is authorized to access Chef 360 Platform services.

    Is the device authorized? (y or n)
> y
Profile:

[tenant-org-role]
DeviceId = "ac:de:48:00:11:22-admin-chef-courier-cli"
Url = "https://chef360.example.com/"
OrgName = "Demo Organization"
RoleName = "org-admin"
AccessKey = "<ACCESS_KEY_STRING>"
SecretKey = "<SECRET_KEY_STRING>"

Device registered successfully

  6. Test your connection by getting the role associated with your user account:

    chef-platform-auth-cli user-account self get-role --profile <PROFILE_NAME>

    Replace <PROFILE_NAME> with the name of your profile.

  7. Optional: Set your new profile as the default profile.

    The Chef 360 Platform CLIs use a default profile automatically in any command that accepts the --profile argument. If you don’t set a default profile, you will have to specify it in each command with --profile <PROFILE_NAME>.

    Set a default profile:

    chef-platform-auth-cli set-default-profile <PROFILE_NAME>

    Replace <PROFILE_NAME> with the name of the default profile.

Verify profiles

Use these commands to verify your profiles and credentials.

  1. List all your profiles with the list-profile-names subcommand. For example:

    chef-platform-auth-cli list-profile-names

    The response is similar to the following:

    List of available profile names:
  1. tenant1
  2. default

    You can use list-profile-names subcommand with any of the Chef 360 Platform CLIs to get a list of your profiles.

  2. Get details of your default profile using the get-default-profile subcommand:

    chef-platform-auth-cli get-default-profile

    The response is similar to the following:

    Default profile:

[default]
DeviceId = "ac:de:48:00:11:22-admin-chef-courier-cli"
Url = "http://tenant-1.dev-360.example.com"
OrgName = "Test OU1"
RoleName = "org-admin"
AccessKey = "FIT3SXM...YK4V05Y"
SecretKey = "Cwaygh4FqE2s...p9IE9YpzoGuX"
Cafile = ""
Insecure = true

    You can use get-default-profile subcommand with any of the Chef 360 Platform CLIs to get your default profile.

Thank you for your feedback!

×