Skip to main content

Install Chef 360 Platform CLIs and register your computer

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 the Chef 360 Platform CLIs

Download and install the CLIs from your Chef 360 Platform UI:

  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.

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

    • chef-courier-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

Optional: Install and configure DSM CLIs

If you are enabling the Chef Declarative State Management (DSM) services, install Knife and configure your workstation to connect to Chef DSM.

Before you begin, you will need your pivotal key. Contact support for instructions to access this.

Follow these steps to install the Knife CLI and configure your workstation:

  1. Install Chef Workstation on your local computer.

  2. Follow the Chef Workstation Getting Started documentation to configure your local computer to connect to Chef DSM.

    In the config.rb file, use the following format for the chef_server_url setting:

    chef_server_url "https://<CHEF_360_FQDN>:31000"

  3. Copy the Pivotal key and place it in the same location as your config.rb file.

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

    knife ssl fetch

    This copies SSL certificates from an HTTPS server to the trusted_certs_dir directory used by Knife and Chef Infra Client to store trusted SSL certificates. The certificate is stored in $HOME/.chef/trusted_certs.

  5. If your 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

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 authorise 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/authorise?oauthCode=<AUTHORIZATION_CODE>&appType=chef-courier-cli&deviceName=<COMPUTER_NAME>  Is the device authorised? (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 authorised? (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 = "FIT3SXM...TCYK4V05Y" SecretKey = "Cwaygh4FqE2sT...rX4wBu0hp9IE9YpzoGuX"  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.

Optional: Assign yourself the node-manager role and create a profile for that role

The node-manager role allows you to manage nodes. If you’ll be managing nodes, assign yourself the node-manager role, create a profile with that role, and authenticate your computer with that profile.

Before you begin, ensure you have:

To assign yourself the node-manager role and create a profile with that role, follow these steps:

  1. Assign the node-manager role using the user-account user assign-role subcommand:

    chef-platform-auth-cli user-account user assign-role \  --body '{"name": "node-manager", "roleId": "6e7df273-928b-41ec-b6f6-e3f5138a6f9e"}' \  --userId <USER_ID> \  --profile <ORG_ADMIN_PROFILE_NAME>

    Replace:

    • <USER_ID> with your user ID.
    • <ORG_ADMIN_PROFILE_NAME> with your profile that has the org-admin role.

  2. Create a profile that you’ll assign the node-manager role to using the register-device subcommand:

    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 you have the root certificate authority present, use the --cafile flag 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 for the role that this profile will use. For example, add the node-manager profile name for the node-manager role.
    • <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 authorise 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/authorise?oauthCode=<AUTHORIZATION_CODE>&appType=chef-courier-cli&deviceName=<COMPUTER_NAME>  Is the device authorised? (y or n)

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

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

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

  5. 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.

  6. 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 authorised? (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 = "node-manager" AccessKey = "FIT3SXM...TCYK4V05Y" SecretKey = "Cwaygh4FqE2sT...rX4wBu0hp9IE9YpzoGuX"  Device registered successfully

  7. Optional: 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.

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

    If you’ll primarily manage nodes, you can set this profile as your 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’ll 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.

Optional: Assign yourself the courier-operator role and create a profile for that role

The courier-operator role allows you to run and manage Chef Courier jobs. If you’ll be managing Courier jobs, assign yourself the courier-operator role, create a profile for that role, and authenticate your computer with that profile.

Before you begin, ensure you have:

To assign yourself the courier-operator role and create a profile with that role, follow these steps:

  1. Assign yourself the courier-operator role using the user-account user assign-role subcommand:

    chef-platform-auth-cli user-account user assign-role \  --body '{"name": "courier-operator", "roleId": "ac12c3a6-95f7-429d-b3fc-584ce1cf74de"}' \  --userId <USER_ID> \  --profile <ORG_ADMIN_PROFILE_NAME>

    Replace:

    • <USER_ID> with your user ID.
    • <ORG_ADMIN_PROFILE_NAME> with your profile that has the org-admin role.

  2. Create a profile that you’ll assign the courier-operator role to using the register-device subcommand. This command 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 you have the root certificate authority present, use the --cafile flag 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 for the role that this profile will use. For example, add the courier-operator profile name for the courier-operator role.
    • <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 authorise 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/authorise?oauthCode=<AUTHORIZATION_CODE>&appType=chef-courier-cli&deviceName=<COMPUTER_NAME>  Is the device authorised? (y or n)

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

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

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

  5. 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.

  6. 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 authorised? (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 = "courier-operator" AccessKey = "FIT3SXM...TCYK4V05Y" SecretKey = "Cwaygh4FqE2sT...rX4wBu0hp9IE9YpzoGuX"  Device registered successfully

  7. Optional: 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.

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

    If you’ll primarily manage Chef Courier jobs, you can set this profile as your 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’ll 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.

More information

See the following:

Next step

Thank you for your feedback!

×