pulp-consumer man page

pulp-consumer — Pulp Documentation


Introducing the Pulp Consumer Client

The Pulp consumer client, pulp-consumer, is a command line tool that allows administrators to register a consumer, bind that consumer to Pulp managed repositories, and install content onto the consumer from those bound repositories.

The client requires the Pulp Agent to be installed in order to communicate with the Pulp server. This is a daemon process that listens on an AMQP bus for messages from the server and uses the bus to send messages to the server.

This page gives a brief introduction to the consumer client and the agent.

Local v. Remote Commands

The pulp-consumer command line client is used to execute Pulp commands locally on the consumer machine. Pulp commands may be executed remotely, from the server, using the pulp-admin command line client. Details on the latter are covered in the pulp-admin documentation.

All commands are available locally. And some commands, namely register are only available locally.

Local Permissions

It is imperative that the pulp-consumer command line client be execute with enough permissions to write system-level configuration and credential files. In general, this will mean with root privileges. This is easiest with the sudo command.

$ sudo pulp-consumer ...

Troubleshooting with verbose flag

You can run pulp-consumer commands in verbose mode to get additional information in case of a failure. Look at the example usage of verbose flag in the admin client troubleshooting section.


In order to register a consumer against the Pulp server, the pulp-consumer command line client provides the register command. A consumer must be registered against a server in order to benefit from the administrative functionality provided by Pulp.

$ sudo pulp-consumer register --consumer-id my-consumer
Enter password:
Consumer [my-consumer] successfully registered

Pre-Registration Authentication

The Pulp server's API is protected by basic authentication requirements. This means that the API is only accessible by defined users with the appropriate credentials.

Before a consumer is registered against a server, the server has no idea who (or what) the consumer is. In order to authenticate against the server's API to register the consumer, basic HTTP Auth credentials must be supplied along with the registration request.


The pulp-consumer command must be executed with root permissions.

$ sudo pulp-consumer register --consumer-id my-consumer
Enter password:
Consumer [my-consumer] successfully registered

The -u and the -p flags supply the HTTP Basic Auth username and password respectively and must correspond to a user defined on the Pulp server. If the -p flag is not supplied, the command line client will ask for the password interactively.


Entering a password on the command line with the -p option is less secure than giving it interactively. The password will be visible to all users on the system for as long as the process is running by looking at the process list. It will also be stored in your bash history.

Post-Registration Authentication

Once a consumer is registered, a certificate is written into its PKI: /etc/pki/pulp/consumer/consumer-cert.pem

This certificate will automatically suffice for authentication against the server's API for all future operations until the consumer is unregistered.

It is worth noting that the pulp-consumer command line client should still be executed with root level permissions.

$ sudo pulp-consumer unregister
Consumer [my-consumer] successfully unregistered


A consumer's attributes are stored on the server when it registers. Those attributes can be updated by using the pulp-consumer update command.

$ pulp-consumer update --help
Command: update
Description: changes metadata of this consumer

Available Arguments:

  --display-name - user-readable display name for the consumer
  --description  - user-readable description for the consumer
  --note         - adds/updates/deletes key-value pairs to programmatically
                   identify the repository; pairs must be separated by an equal
                   sign (e.g. key=value); multiple notes can be changed by
                   specifying this option multiple times; notes are deleted by
                   specifying "" as the value

Here is an example of updating the display name:

$ pulp-consumer update --display-name="Consumer 1"
Consumer [con1] successfully updated


Once a consumer is registered to a Pulp server, it can then bind to a repository. Binding allows content from a specific repository on the server to be installed on the consumer. Installation of content can be initiated either on the consumer or from the server. For example, in the case of RPM content, binding sets up a repository as a normal yum repository on the consumer. Packages can be installed with normal yum commands or by initiating an install through the Pulp server.


Binding to a server requires the consumer to first register. Then a bind command can be issued for a specific repository. Similar to the pulp-admin command, type-specific operations such as bind are located under a section bearing the type's name.

$ pulp-consumer rpm bind --repo-id=zoo
Bind tasks successfully created:

Task Id: 6e48ce85-60a0-4bf6-b2bb-9617eb7b3ef3

Looking at the consumer history, the first action in the list is a bind action to the specified repository.

$ pulp-consumer history --limit=1
                        Consumer History [con1]

Consumer Id:  con1
Type:         repo_bound
  Distributor Id: yum_distributor
  Repo Id:        zoo
Originator:   SYSTEM
Timestamp:    2013-01-02T22:01:17Z

It may take a few moments for the bind to take effect. It happens asynchronously in the background, and we are working on a way to show positive confirmation of success from pulp-consumer.


Unbinding is equally simple.

$ pulp-consumer rpm unbind --repo-id=zoo
Unbind tasks successfully created:

Task Id: 0c02d974-cf00-44b7-9b63-cdadfc9bfab7

Looking at the history, it is clear that the consumer is no longer bound to the repository.

$ pulp-consumer history --limit=1
                        Consumer History [con1]

Consumer Id:  con1
Type:         repo_unbound
  Distributor Id: yum_distributor
  Repo Id:        zoo
Originator:   SYSTEM
Timestamp:    2013-01-02T22:09:47Z

In case a consumer is bound to a repository on a Pulp server that is no longer available, the --force option will make all of the local changes necessary to unbind from the remote repository without requiring the server to participate. When using this option, make sure a similar action is taken on the server so it does not continue to track a binding with the consumer.


Pulp Server keeps track of operations performed on its consumers in the consumer's history. The events tracked in the history and their respective event types are as follows:

  • Consumer Registered - consumer_registered
  • Consumer Unregistered - consumer_unregistered
  • Repository Bound - repo_bound
  • Repository Unbound - repo_unbound
  • Content Unit Installed - content_unit_installed
  • Content Unit Uninstalled - content_unit_uninstalled
  • Unit Profile Changed - unit_profile_changed
  • Added to a Consumer Group - added_to_group
  • Removed from a Consumer Group - removed_from_group

Note that only operations that are triggered through Pulp are logged. If the consumer installs a content unit through another means (eg. rpm, yum etc.) an event will not be logged. The package profile, however, will eventually be sent to the server and will reflect any changes that have been made.

A consumer can view its own history using the consumer history command.  A number of query arguments may be passed in to the consumer history command in order to refine the results. Here are a few examples of querying consumer history:

$ pulp-consumer history --limit 2 --sort ascending --event-type repo_bound
                      Consumer History [consumer1]

Consumer Id:  test-consumer
Type:         repo_bound
  Distributor Id: yum_distributor
  Repo Id:        test-repo1
Originator:   SYSTEM
Timestamp:    2013-01-17T05:43:36Z

Consumer Id:  test-consumer
Type:         repo_bound
  Distributor Id: yum_distributor
  Repo Id:        test-repo2
Originator:   SYSTEM
Timestamp:    2013-01-17T05:49:09Z
$ pulp-consumer history --start-date 2013-01-17T19:00:00Z --end-date 2013-01-17T21:00:00Z
                      Consumer History [consumer1]

Consumer Id:  consumer1
Type:         consumer_registered
Details:      None
Originator:   admin
Timestamp:    2013-01-17T19:14:49Z


You can check registration status of a consumer using pulp-consumer status command. With this command you can get the information about which server the consumer is registered to and the consumer id used for the registration.

$ pulp-consumer status
This consumer is registered to the server [test-pulpserver.rdu] with the ID [f17-test-consumer].

When the consumer is not registered to a pulp server, it will simply display a message stating the same.

$ pulp-consumer status
This consumer is not currently registered.


This guide covers consumer client commands for managing Pulp Nodes in the Pulp Platform. For an overview, tips, and, troubleshooting, please visit the Pulp Nodes Concepts Guide.


The root level node section contains the following features.

$ pulp-consumer node --help
Usage: pulp-consumer [SUB_SECTION, ..] COMMAND
Description: pulp nodes related commands

Available Commands:
 activate   - activate a consumer as a child node
 bind       - bind this node to a repository
 deactivate - deactivate a child node
 unbind     - remove the binding between this node and a repository


A Pulp server that is registered as a consumer to another Pulp server can be designated as a child node. Once activated on the parent server, the consumer is recognized as a child node of the parent and can be managed using node commands.

To activate a consumer as a child node, use the node activate command. More information on node-level synchronization strategies can be found here.

$ pulp-consumer node activate --help
Command: activate
Description: activate a consumer as a child node

Available Arguments:

 --strategy - synchronization strategy (mirror|additive) default is additive

A child node may be deactivated using the node deactivate command. Once deactivated, the node may no longer be managed using node commands.

$ pulp-consumer node deactivate --help
Command: deactivate
Description: deactivate a child node

Consumer un-registration will automatically deactivate the node.


The node bind command is used to associate a child node with a repository on the parent. This association determines which repositories may be synchronized to child nodes. The strategy specified here overrides the default strategy specified when the repository was enabled. More information on repository-level synchronization strategies can be  found here.

$ pulp-consumer node bind --help
Command: bind
Description: bind this node to a repository

Available Arguments:

 --repo-id  - (required) unique identifier; only alphanumeric, -, and _ allowed
 --strategy - synchronization strategy (mirror|additive) default is additive

The node unbind command may be used to remove the association between a child node and a repository. Once the association is removed, the specified repository can no longer be be synchronized to the child node.

$ pulp-consumer node unbind --help
Command: unbind
Description: remove the binding between this node and a repository

Available Arguments:

 --repo-id - (required) unique identifier; only alphanumeric, -, and _ allowed

Only activated nodes and enabled repositories may be specified.


Pulp Team


Apr 18, 2017 2.12.2 Pulp Project