Settings¶
There are only two required settings, although specific plugins may have additional required settings.
SECRET_KEY <secret-key-setting>
CONTENT_ORIGIN <content-origin-setting>
Note
For more information on how to specify settings see the Applying Settings
.
Pulp uses three types of settings:
Django settings
Pulp is configuringRedis settings
Pulp is usingPulp defined settings
Django Settings¶
Below is a list of the most common Django settings Pulp users typically use. Pulp is a Django project, so any Django setting can be set.
SECRET_KEY¶
In order to get a pulp server up and running a Django SECRET_KEY must be provided. The following code snippet can be used to generate a random SECRET_KEY.
1 2 3 4 |
|
DB_ENCRYPTION_KEY¶
The file location of a symmetric fernet key that Pulp uses to encrypt sensitive fields in the
database. Default location is /etc/pulp/certs/database_fields.symmetric.key
.
The key is automatically generated by default with the pulp-oci-images. The key can be generated
independently but it must be a url-safe base64-encoded string of 32 random bytes.
To generate a key with openssl:
openssl rand -base64 32 > /etc/pulp/certs/database_fields.symmetric.key
This file can contain multiple such keys (one per line). The key in the first line will be used for encryption but all others will still be attempted to decrypt old tokens. This can help you to rotate this key in the following way:
- Shut down all Pulp services (api, content and worker processes).
- Add a new key at the top of the key file.
- Call
pulpcore-manager rotate-db-key
. - Remove the old key (on the second line) from the key file.
- Start the Pulp services again.
For a zero downtime key rotation you can follow the slightly more complex recipe:
- Add a new key at the bottom of the key file.
- Restart the Pulp services in the usual phased manner.
- Swap the keys in the key file.
- Restart the Pulp services again.
- Call
pulpcore-manager rotate-db-key
. - Remove the old key (on the second line) from the key file.
- Restart the Pulp services for the last time.
DATABASES¶
By default Pulp uses PostgreSQL on localhost. PostgreSQL is the only supported database. For
instructions on how to configure the database, refer to database installation <database-install>
.
DEFAULT_FILE_STORAGE¶
By default, Pulp uses the local filesystem to store files. The default option which
uses the local filesystem is pulpcore.app.models.storage.FileSystem
.
For more information about different Pulp storage options, see the
storage documentation
.
REDIRECT_TO_OBJECT_STORAGE¶
When set to True
access to artifacts is redirected to the corresponding Cloud storage
configured in DEFAULT_FILE_STORAGE
using pre-authenticated URLs. When set to False
artifacts are always served by the content app instead.
Defaults to True
; ignored for local file storage.
MEDIA_ROOT¶
The location where Pulp will store files. By default this is /var/lib/pulp/media
.
This only affects storage location when DEFAULT_FILE_STORAGE
is set to
pulpcore.app.models.storage.FileSystem
. See the storage documentation
for
more info.
It should have permissions of:
- mode: 750
- owner: pulp (the account that pulp runs under)
- group: pulp (the group of the account that pulp runs under)
- SELinux context: system_u:object_r:pulpcore_var_lib_t:s0
LOGGING¶
By default Pulp logs at an INFO level to syslog. For all possible configurations please refer to Django documenation on logging
Enabling DEBUG logging is a common troubleshooting step. See the enabling-debug-logging
documentation for details on how to do that.
AUTHENTICATION_BACKENDS¶
By default, Pulp has two types of authentication enabled, and they fall back for each other:
- Basic Auth which is checked against an internal users database
- Webserver authentication that relies on the webserver to perform the authentication.
To change the authentication types Pulp will use, modify the AUTHENTICATION_BACKENDS
settings. See the Django authentication documentation for more information.
Redis Settings¶
Warning
To enable usage of Redis the [CACHE_ENABLED] option must be set to True
.
The following Redis settings can be set in your Pulp config:
- REDIS_URL
- REDIS_HOST
- REDIS_PORT
- REDIS_DB
- REDIS_PASSWORD
Below are some common settings used for Redis configuration.
REDIS_HOST¶
The hostname for Redis.
REDIS_PORT¶
The port for Redis.
REDIS_PASSWORD¶
The password for Redis.
Pulp Settings¶
Pulp defines the following settings itself:
API_ROOT¶
A string containing the path prefix for the Pulp API. This is used by the REST API when forming
URLs to refer clients to other parts of the REST API and by the pulpcore-api
application to
match incoming URLs. Pulp appends the string api/v3/
to this setting.
Defaults to /pulp/
. After the application appends api/v3/
it makes the V3 API by default
serve from /pulp/api/v3/
.
WORKING_DIRECTORY¶
The directory used by workers to stage files temporarily. This defaults to
/var/lib/pulp/tmp/
.
It should have permissions of:
- mode: 750
- owner: pulp (the account that pulp runs under)
- group: pulp (the group of the account that pulp runs under)
- SELinux context: system_u:object_r:pulpcore_var_lib_t:s0
Note
It is recommended that WORKING_DIRECTORY
and MEDIA_ROOT
exist on the same storage
volume for performance reasons. Files are commonly staged in the WORKING_DIRECTORY
and
validated before being moved to their permanent home in MEDIA_ROOT
.
CHUNKED_UPLOAD_DIR¶
A relative path inside the DEPLOY_ROOT directory used exclusively for uploaded chunks. The
uploaded chunks are stored in the default storage specified by DEFAULT_FILE_STORAGE
. This
option allows users to customize the actual place where chunked uploads should be stored within
the declared storage. The default, upload
, is sufficient for most use cases. A change to
this setting only applies to uploads created after the change.
CONTENT_ORIGIN¶
A required string containing the protocol, fqdn, and port where the content app is reachable by
users. This is used by pulpcore
and various plugins when referring users to the content app.
For example if the API should refer users to content at using http to pulp.example.com on port
24816, (the content default port), you would set: https://pulp.example.com:24816
.
HIDE_GUARDED_DISTRIBUTIONS¶
If activated, the distributions that are protected by a content guard will not be shown on the
directory listing in the content app. Defaults to False
.
CONTENT_PATH_PREFIX¶
A string containing the path prefix for the content app. This is used by the REST API when forming URLs to refer clients to the content serving app, and by the content serving application to match incoming URLs.
Defaults to /pulp/content/
.
CONTENT_APP_TTL¶
The number of seconds before a content app should be considered lost.
Defaults to 30
seconds.
CACHE_ENABLED¶
Store cached responses from the content app into Redis. This setting improves the performance
of the content app under heavy load for similar requests. Defaults to False
.
Note
The entire response is not stored in the cache. Only the location of the file needed to recreate the response is stored. This reduces database queries and allows for many responses to be stored inside the cache.
CACHE_SETTINGS¶
Dictionary with tunable settings for the cache:
EXPIRES_TTL
- Number of seconds entries should stay in the cache before expiring.
Defaults to 600
seconds.
Note
Set to None
to have entries not expire.
Content app responses are always invalidated when the backing distribution is updated.
DOMAIN_ENABLED¶
Note
This feature is provided as a tech-preview
Enable the Domains feature to enable multi-tenancy capabilities <domains>
. All installed
plugins must be Domain compatible for Pulp to start. Defaults to False
.
WORKER_TTL¶
The number of seconds before a worker should be considered lost.
Defaults to 30
seconds.
REMOTE_USER_ENVIRON_NAME¶
The name of the WSGI environment variable to read for webserver authentication
<webserver-authentication>
.
Warning
Configuring this has serious security implications. See the Django warning at the end of this section in their docs for more details.
Defaults to 'REMOTE_USER'
.
ALLOWED_IMPORT_PATHS¶
One or more real filesystem paths that Remotes with filesystem paths can import from. For example
to allow a remote url of file:///mnt/foo/bar/another/folder/
you could specify:
ALLOWED_IMPORT_PATHS = ['/mnt/foo/bar'] # only a subpath is needed
Defaults to []
, meaning file:///
urls are not allowed in any Remote.
ALLOWED_EXPORT_PATHS¶
One or more real filesystem paths that Exporters can export to. For example to allow a path of
/mnt/foo/bar/another/folder/
you could specify:
ALLOWED_EXPORT_PATHS = ['/mnt/foo/bar'] # only a subpath is needed
Defaults to []
which means no path is allowed.
ALLOWED_CONTENT_CHECKSUMS¶
Warning
Enforcement of this setting in pulpcore
and various plugins is not fully in place. It is
possible that checksums not in this list may still be used in various places. This banner will
be removed when it is believed all pulpcore
and plugin code fully enforces this setting.
The list of content-checksums this pulp-instance is allowed to use. By default the following are used:
ALLOWED_CONTENT_CHECKSUMS = ["sha224", "sha256", "sha384", "sha512"]
The entire set of supported checksums are: md5
, sha1
, sha224
, sha256
,
sha384
, and sha512
.
Warning
Due to its use as the primary content-identifier, "sha256" IS REQUIRED. Pulp will
fail to start if "sha256"
is not found in this set.
Pulp can prohibit or allow checksums by setting the ALLOWED_CONTENT_CHECKSUMS setting. Changing this setting requires a few steps.
First, before you change the setting, see how your Pulp instance will be impacted by this change by running:
pulpcore-manager handle-artifact-checksums --report --checksums sha256,512
Adjust --checksums
as comma separated list of checksums types to match your needs.
Note
If you already changed ALLOWED_CONTENT_CHECKSUMS
in pulp settings you can leave out --checksums
,
and the checksums will be parsed from Pulp settings.
Before switching, any on-demand repos containing forbidden checksum digests needs to be synced with
policy=immediate
to populate missing allowed checksums. This can heavily impact your disk space.
Alternatively, users can remove these offending repo versions followed by orphan cleanup.
If you have artifacts that do not conform to your ALLOWED_CONTENT_CHECKSUMS setting, they need to be re-hashed. You can update them using:
pulpcore-manager handle-artifact-checksums
Warning
If Pulp fails to start because forbidden checkums have been identified or required ones are
missing, run pulpcore-manager handle-artifact-checksums
command.
DJANGO_GUID¶
Pulp uses django-guid
to append correlation IDs to logging messages. Correlation IDs are
autogenerated by default but can also be sent as a header with each request. They are also
returned as a header in the response and are recorded in the logging_cid
field of tasks.
For more information on how to configure the DJANGO_GUID
setting, see the django-guid
settings documentation.
ORPHAN_PROTECTION_TIME¶
The time specified in minutes for how long Pulp will hold orphan Content and Artifacts before they become candidates for deletion by an orphan cleanup task. This should ideally be longer than your longest running task otherwise any content created during that task could be cleaned up before the task finishes. Default is 1440 minutes (24 hours).
UPLOAD_PROTECTION_TIME, TMPFILE_PROTECTION_TIME and TASK_PROTECTION_TIME¶
Pulp uses tasks
, uploads
and pulp temporary files
to pass data from the api to worker tasks.
These options allow to specify a timeinterval in minutes used for cleaning up stale entries.
If set to 0, automatic cleanup is disabled, which is the default.
TASK_DIAGNOSTICS¶
The default setting is False
. When set to True
, each task records various diagnostics (listed below)
and stores them as separate artifacts. To download the data, issue GET requests to ${TASK_HREF}profile_artifacts/
.
The artifacts are cleaned up automatically by the orphan cleanup.
- memory.datum - the task's max resident set size in MB
- pyinstrument.html - the output of the pyinstrument profiler, if installed
ANALYTICS¶
If True
, Pulp will anonymously post analytics information to
https://analytics.pulpproject.org/ and aids in project decision making. See the
analytics docs
for more info on exactly what is posted along with an example.
Defaults to True
.
Kafka Settings¶
Note
Kafka integration functionality is in tech preview and may change based on user feedback.
See librdkafka configuration documentation for details on client configuration properties.
KAFKA_BOOTSTRAP_SERVERS¶
bootstrap.servers
value for the client. Specifies endpoint(s) for the kafka client. Kafka integration is disabled if
unspecified.
KAFKA_SECURITY_PROTOCOL¶
security.protocol
value for the client. What protocol to use for communication with the broker.
Defaults to plaintext
(unencrypted).
KAFKA_SSL_CA_PEM¶
ssl.ca.pem
value for the client (optional). Used to override the TLS truststore for broker connections.
KAFKA_SASL_MECHANISM¶
sasl.mechanisms
value for the client (optional). Specifies the authentication method used by the kafka broker.
KAFKA_SASL_USERNAME¶
sasl.username
value for the client (optional). Username for broker authentication.
KAFKA_SASL_PASSWORD¶
sasl.password
value for the client (optional). Password for broker authentication.
KAFKA_TASKS_STATUS_TOPIC¶
What kafka topic to emit notifications to when tasks start/stop.
Defaults to pulpcore.tasking.status
.
KAFKA_TASKS_STATUS_PRODUCER_SYNC_ENABLED¶
Whether to synchronously send task status messages. When True
, the task message is sent synchronously, otherwise the
sends happen asynchronously, with a background thread periodically sending messages to the kafka server.
Defaults to False
.
KAFKA_PRODUCER_POLL_TIMEOUT¶
Timeout in seconds for the kafka producer polling thread's poll
calls.
Defaults to 0.1
.