Pulp Consumer Client

Introduction

The pulp-consumer script is used by a system to become a Pulp consumer. A consumer is essentially a system that uses Pulp for repository binding and package profile tracking.

All commands are issued by passing the command string to the pulp-consumer script. For example, to display the consumer's history, the consumer history command is run:

$ pulp-consumer consumer history

Arguments to a command are specified after the command and begin with --. All commands support the --help argument to display more information on the possible arguments supported:

$ pulp-consumer consumer register --help

The pulp-consumer script must be run as root due to the fact that it creates and manages yum repository files.

Configuration

Configuration for the pulp-consumer script is done through the /etc/pulp/consumer/consumer.conf file. The configuration options are divided into the following sections:

Server

The following options control the communications from consumer to Pulp server.

Name	Description
`host`	Fully qualified hostname of the Pulp server. In addition to being used to find the server itself, this is also used to verify the server's SSL certificate. As such, this cannot simply be the IP of the Pulp server and must be the hostname configured in the server's SSL certificate.
`port`	Port on which the Pulp server API is hosted. The default is 443 (HTTPS) and will likely not need to be changed.
`scheme`	Currently, only https is supported.
`interval`	Frequency in minutes at which the package profile is sent to the server.

Client Configuration

The following control the behavior of the client and the operations it performs.

Name	Description
`reboot_schedule`	Time in minutes or 'now' before system is scheduled for reboot when user requests a reboot for applicable errata.
`assumeyes`	Default: `true`. If true, when a package is remotely installed by a Pulp user through `pulp-admin` that requires a reboot as part of the installation the reboot will automatically take place.

Pulp Agent

To support Pulp command & control, Pulp provides a light weight agent. The agent is included in the pulp-consumer package and is installed as a service. The pulp-agent service should be configured to start automatically.

# chkconfig pulp-agent on

CDS

The following control the locations of content served by the Pulp server. In most cases, only the host portion of the URLs should need to be changed.

Name	Description
`baseurl`	Base URL of repositories served by the Pulp server.
`keyurl`	URL where repository GPG public keys are accessible.
`ksurl`	URL where kickstart information can be accessed.

Registration

In order to use a system as a consumer of a Pulp server, it must be registered against the server. Registration is done through the `consumer register` command. When a consumer is registered, it provides a unique (to the Pulp server) ID to identify itself. For example, to register a consumer with the ID "example", the following command would be used:

$ pulp-consumer consumer register --id example

The following attributes can be specified at consumer registration (all attributes are optional unless otherwise specified).

Name	Flag	Description
ID	`--id`	Required. Uniquely identifies this consumer in the Pulp server.
Description	`--description`	Optional text to describe the consumer; this is displayed when using `pulp-admin` to view consumer information.

Unregistration

A consumer can opt to remove its relationship with a Pulp server using the consumer unregister command. There are no arguments to the command, it is simply called on a previously-registered consumer:

$ pulp-consumer consumer unregister

History

Pulp keeps track of operations performed on its consumers in the consumer's history. The following operations are tracked:

Consumer Registered
Consumer Unregistered
Repository Bound
Repository Unbound
Package Installed*
Package Removed*
Errata Installed*
Profile Changed

Only package/errata operations that are triggered through Pulp are logged. If the consumer installs a package through another means (rpm or yum) 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:

$ pulp-consumer consumer history

A number of query arguments may be passed in to the consumer history command in order to refine the results. The following query parameters are provided.

Name	Flag	Description
Event Type	`--event_type`	Limits the results to only those that match the given event type. The programmatic names for the event types can be found by running the `consumer history --help` command.
Limit	`--limit`	Only displays the given number of history entries. Value must be greater than zero.
Sort	`--sort`	Sorts the history entries according to timestamp. Valid values are "ascending" and "descending". Default is descending.
Start Date	`--start_date`	Limits the returned entries to on or after the given date. The format follows the Date Units guidelines.
End Date	`--end_date`	Limits the returned entries to on or before the given date. The format follows the Date Units guidelines.

These parameters may be combined to form advanced queries.

$ pulp-consumer consumer history --limit 3 --event_type repo_bound --start_date 2011-01-01 --end_date 2011-01-31
+------------------------------------------+
              Consumer History
+------------------------------------------+

Event Type            	Repo Bound               
Timestamp             	2011-01-10 13:42:16.780000
Originator            	admin                    
Repo ID               	example

Package Profile

A consumer's package profile is an inventory of installed packages on the client, including their names, versions, and architecture. Consumers automatically send an updated package profile to the Pulp server at regular intervals (see the Client Configuration section for more information on the frequency).

Repository Binding

Bind

A consumer can use repositories in Pulp through a process called binding. Once configured, bound repositories are added to the consumer's yum repository list and are available for package installation either by the pulp-admin script or through yum. All bound repositories are found in the /etc/yum.repos.d/pulp.repo file.

Repositories are bound through the consumer bind command:

$ pulp-consumer consumer bind --repoid example
Successfully subscribed consumer [test-consumer] to repo [example]

The list of repositories a consumer has access to can be found through the repo list command:

$ pulp-consumer repo list
+------------------------------------------+
       List of Available Repositories
+------------------------------------------+

Label              	example                  
Name               	example                  
FeedURL            	http://example.com/repos 
FeedType           	yum                      
Arch               	noarch                   
Sync Schedule      	None                     
Packages           	0                        
Files              	0                        
Distributions      	None                     
Publish            	True                     
Clones             	[]                       
Groups             	None

Note: The "Label" field in the above output is the value used for --repoid in the bind command.

Unbind

A consumer can remove its association from a repository through the consumer unbind command. Like consumer bind, this command takes a single argument --repoid which identifies the repository to unbind:

$ pulp-consumer consumer unbind --repoid example
Successfully unsubscribed consumer [test-consumer] from repo [example]