Conjur CLI

The Conjur CLI implements the Conjur REST API, providing an alternate interface for administering Conjur resources, including roles, privileges, policy, and secrets. You can start a CLI client session as a container local to the Conjur appliance, or remotely on a workstation.

CLI Releases

The Conjur CLI is an open source tool that works for both Conjur Enterprise V5 and Conjur Open Source V1. We distribute the CLI as a containerized package on DockerHub and as a Ruby gem on GitHub.The same distribution works for both Conjur Enterprise V5 and Conjur Open Source V1. See the GitHub repo here.

 

CLI Release Train: 

Conjur CLI v6.x.x is the correct release train for Conjur Enterprise V5 and Conjur Open Source V1. To avoid confusion for Conjur Enterprise V5 users, the DockerHub label is conjur-cli:5. Be assured that it contains the latest released version from the CLI v6 release train.

Start a CLI Container

This procedure pulls the latest CLI image from DockerHub, initializes to Conjur, and authenticates to Conjur.

  1. Create the CLI container:

    If Conjur container is local: 

     
    $ docker run --rm -it -v "<folder-on-server>:\<folder-in-container>" --link <conjur-container-name> cyberark/conjur-cli:5

    If Conjur container is reachable over the DNS network: (omit the --link option)

     
    $ docker run --rm -it -v "<folder-on-server>:\<folder-in-container>" cyberark/conjur-cli:5

    where:

    Attribute

    Description

    <folder-on-server>:\folder-in-container

    The -v option is required if you are planning to create or modify policy files; it is optional otherwise. Mapping a folder from your server into the container is required so that the files and any changes you make to them will persist after you close the CLI container.

     

    Do not confuse the concept of creating and editing policy files with the concepts of loading and updating policy into Conjur. Any policy that is successfully loaded into Conjur will persist in the database regardless of what happens to the policy files that were used to load the statements.

    <folder-on-server> is the persistent location of files, such as policy files.

     

    <folder-in-container> is the temporary mapping into the container.

    For example: 

    -v "$(pwd):/foo" maps your current folder to a folder named foo inside the container.

    <conjur-container-name>

    If local, use the container name of the Conjur appliance.

    If running the CLI client on another machine, this argument is not used.

    .

    For example:

     
    $ docker run --rm -it -v "$(pwd)/policy-files:/policy-files" --link conjur-appliance cyberark/conjur-cli:5

    or

     
    $ docker run --rm -it -v "$(pwd)/policy-files:/policy-files" cyberark/conjur-cli:5

    The example does the following:

      • Starts a container, assigning it an arbitrary name.

      • Removes the container when you exit the container.

      • Creates an interactive Bash session within the container.

      • Maps a folder named policy-files in your current directory $(pwd) to a folder named policy-files in the CLI container that is started.

      • If running locally, connects the CLI container to the Conjur appliance. If running remotely, DNS will make the connection using the URL you supply in the conjur init command in the next step.

      • Pulls the latest image from Dockerhub. This image can be used to connect to both Conjur Open Source V1 and Conjur Enterprise V5.

    If the command is successful, you are placed into the Bash session within the new container.

  2. Initialize to Conjur.

    1. At the Bash prompt, enter conjur init.

    2. Provide the URL of the Conjur appliance in the format https://<host-name>.

    3. Answer yes to the prompt about trusting the Conjur self-signed certificates.

    4. Enter the organizational account that was assigned to this Conjur appliance at installation.

    This command creates a self-signed certificate and writes files in your root directory. For example:

     
    # conjur init 
    Enter the URL of your Conjur service: https://conjur.node1.example
    
    SHA1 Fingerprint=FD:07:9C:79:B5:61:7C:B2:EB:E3:87:E8:5A:83:6F:3A:2F:C5:5E:06
    
    Please verify this certificate on the appliance using command:
                  openssl x509 -fingerprint -noout -in ~conjur/etc/ssl/conjur.pem
    
    Trust this certificate (yes/no): yes
    Enter your organization account name: demo
    Wrote certificate to /root/conjur-demo.pem
    Wrote configuration to /root/.conjurrc
    
  3. Authenticate to Conjur.

    1. Enter conjur authn login <user-name>.

      <user-name> must be a valid Conjur user name or the value admin.

    2. Enter the password at the prompt.

      An initial password was assigned to the admin user at installation. Recommended practice is to log in as admin immediately after installation and change the password. A user can change his own password only after logging in with the existing password, using conjur user update_password .

     
    # conjur authn login jane
    Please enter jane's password (it will not be echoed):
    Logged in
    #
    

Alternate Ways to Start a CLI Container

The previous procedure is one way to create a CLI container that interacts with a Conjur appliance. Developers might modify this procedure for a production environment to create a customized optimal experience. For example:

  • The docker run command offers many options and flags that can enhance your user experience depending on your environment and goals.

  • This procedure starts a highly secure ephemeral container for the CLI that removes all files when it stops. See the CLI readme for a way to persist identity data so that subsequent sessions are quicker to start up.

  • If you have a Ruby environment, you may choose to install the Ruby gem. See the CLI readme.

Upgrades

After initial installation, use the CLI Changelog on GitHub to read about new CLI releases as they become available. The Changelog contains links to the distributions for each new release.

Help and Documentation

For CLI documentation, use the command line help options:

  1. To see a list of Conjur commands, enter conjur --help .

     
    # conjur --help
    NAME
        conjur - Command-line toolkit for managing roles, resources and privileges
    
    SYNOPSIS
        conjur [global options] command [command options] [arguments...]
    
    VERSION
        6.2.0
    
    GLOBAL OPTIONS
        --help    - Show this message
        --version - Display the program version
    
    COMMANDS
        authn       - Login and logout
        check       - Check for a privilege on a resource
        env         - Use values of Conjur variables in local context
        help        - Shows a list of commands or help for one command
        host        - Manage hosts
        hostfactory - Manage host factories
        init        - Initialize the Conjur configuration
        ldap-sync   - LDAP sync management commands
        list        - List objects
        plugin      - Manage plugins
        policy      - Manage policies
        pubkeys     - Public keys service operations
        resource    - Manage resources
        role        - Manage roles
        show        - Show an object
        user        - Manage users
        variable    - Manage variables
    
  2. To see a list of subcommands under a major command: 

     
    # conjur <command> --help

    For example, see the subcommands under the user command:

     
    # conjur user --help
    NAME
        user - Manage users
    
    SYNOPSIS
        conjur [global options] user rotate_api_key [--user arg|-u arg]
        conjur [global options] user update_password [-p arg|--password arg]
    
    COMMANDS
        rotate_api_key  - Rotate a user's API key
        update_password - Update the password of the logged-in user
    
  3. To see help on a specific subcommand:

     
    # conjur <command> <subcommand> --help

    For example, get syntax and options for the user list subcommand:

     
    # conjur user update_password --help
    NAME
        update_password - Update the password of the logged-in user
    
    SYNOPSIS
        conjur [global options] user update_password [command options] 
    
    COMMAND OPTIONS
        -p, --password=arg - Password to use, otherwise you will be prompted (default: none)