#3098 Add all options to hub_conf.rst
Merged 5 months ago by tkopecek. Opened 7 months ago by jcupova.
jcupova/koji issue-3073  into  master

Add all options to hub_conf.rst
Jana Cupova • 5 months ago  
file modified
+501 -19
@@ -1,15 +1,485 @@ 

- hub.conf

- --------

- hub.conf is a standard .ini-like configuration file. Its main section is

- called ``[hub]`` and contains the following options. They can occur anywhere.

+ Hub Configuration Options

+ -------------------------

+ The hub can be configured via one or more ini-style configuration files.

+ Options below should be placed in the ``[hub]`` section of these files.

  

- Incomplete document

- ^^^^^^^^^^^^^^^^^^^

+ These files can also contain a ``[policy]`` section for configuring policies.

+ This is described in :doc:`policy <defining_hub_policies>`.

  

- This document is a stub and does not cover all options.

- Work to complete this document is tracked in `Issue 3073 <https://pagure.io/koji/issue/3073>`_

+ File locations

+ ^^^^^^^^^^^^^^

  

- The old :doc:`Server HOW TO <server_howto>` doc also describes some hub configuration options.

+ By default, koji-hub will read a primary configuration file at

+ ``/etc/koji-hub/hub.conf`` and any number of supplemental configuration

+ files in the ``/etc/koji-hub/hub.conf.d`` directory.

+ Options in the primary configuration file take precedence in case of duplication.

+ 

+ If needed, these locations can be changed by setting the environment variables

+ ``koji.hub.ConfigFile`` and ``koji.hub.ConfigDir`` respectively, e.g. by using

+ the SetEnv directive in the httpd configuration.

+ 

+ A common pattern is to place policy rules and/or sensitive values in separate configuration

+ files.

+ 

+ 

+ File permissions

+ ^^^^^^^^^^^^^^^^

+ 

+ Note some configuration options (e.g. database password) are sensitive values.

+ Our default packaging installs ``hub.conf`` with 0640 root/apache file permissions.

+ If you're installing some other way, we recommend that you double-check these permissions.

+ 

+ Basic options

+ ^^^^^^^^^^^^^

+ .. glossary::

+    DBName

+       Type: string

+ 

+       Default: ``None``

+ 

+       The name of the database that the hub should connect to.

+ 

+    DBHost

+       Type: string

+ 

+       Default: ``None``

+ 

+       The hostname that the database is running on.

+ 

+       Note: If your database server is running locally and you would like to connect

+       via Unix socket instead of TCP, then omit the ``DBHost`` and ``DBPort`` options.

+       If you set ``DBHost`` to ``localhost``, then the connection will be over TCP.

+ 

+    DBPort

+       Type: string

+ 

+       Default: ``None``

+ 

+       The port to use when connecting to the database over TCP.

+ 

+    DBUser

+       Type: string

+ 

+       Default: ``None``

+ 

+       The database user to connect as.

+ 

+    DBPass

+       Type: string

+ 

+       Default: ``None``

+ 

+       The password for connecting to the database.

+ 

+       Please ensure that your hub configuration file(s) have appropriate file permissions

+       before placing sensitive data in them.

+ 

+    DBConnectionString

+       Type: string

+ 

+       Default: ``None``

+ 

+       The connection string (dsn) for connecting to the database.

+       This overrides the other ``DB*`` options.

+       This value is passed through to psycopg2 and would typically look something like:

+       ``dbname=koji user=koji host=db.example.com port=5432 password=example_password``

+ 

+    KojiDir

+       Type: string

+ 

+       Default: ``/mnt/koji``

+ 

+       This is the root directory for koji files.

+ 

+ The database connection can be specified either by the single ``DBConnectionString``

+ option, or by other individual ``DB*`` options.

+ If given, the ``DBConnectionString`` option takes precedence.

+ 

+ General authentication options

+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+ .. glossary::

+    CheckClientIP

+       Type: boolean

+ 

+       Default: ``True``

+ 

+       Use user IP in session management.

+ 

+    LoginCreatesUser

+       Type: boolean

+ 

+       Default: ``True``

+ 

+       Whether or not to automatically create a new user from valid ssl or gssapi credentials.

+ 

+ GSSAPI authentication options

+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+ 

+ The following options control aspects of authentication when using ``mod_auth_gssapi``.

+ 

+ .. glossary::

+    ProxyPrincipals

+       Type: string

+ 

+       Default: ``None``

+ 

+       A comma separated list of principals that are allowed to perform proxy authentication.

+       This ability is only intended for kojiweb.

+ 

+    HostPrincipalFormat

+       Type: string

+ 

+       Default: ``None``

+ 

+       This format string is used to set the principal when adding new hosts.

+       The ``%s`` is expanded to the hostname.

+       If a specific principal is given to the ``add-host`` command then this option

+       is not used.

+ 

+    AllowedKrbRealms

+       Type: string

+ 

+       Default: ``*``

+ 

+       Allowed Kerberos Realms. The default value "*" indicates any Realm is allowed.

+       This is a comma separated list.

+ 

+    DisableGSSAPIProxyDNFallback

+       Type: boolean

+ 

+       Default: ``False``

+ 

+       If True, enables backwards compatible behavior in the handling of the ``ProxyDNs``

+       option.

+       The default value of False is recommended.

+ 

+ Enabling gssapi auth also requires settings in the httpd config.

+ 

+ SSL client certificate auth configuration

+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+ If using SSL auth, these settings need to be valid and in line with other services configurations

+ for kojiweb to allow logins.

+ 

+ .. glossary::

+    DNUsernameComponent

+       Type: string

+ 

+       Default: ``CN``

+ 

+       The client username is the common name of the subject of their client certificate.

+ 

+    ProxyDNs

+       Type: string

+ 

+       Default: ``''``

+ 

+       If specified, the given DNs are allowed to perform proxy authentication.

+       This ability is only intended for kojiweb.

+       Multiple DNs can be separated with the vertical bar character, ``|``.

+ 

+ Enabling ssl auth also requires editing the httpd config (conf.d/kojihub.conf).

+ 

+ Notification options

+ ^^^^^^^^^^^^^^^^^^^^

+ .. glossary::

+    KojiWebURL

+       Type: string

+ 

+       Default: ``http://localhost.localdomain/koji``

+ 

+       This specifies the URL address of Koji web.

+       This setting affects the links that appear in notification messages.

+ 

+    EmailDomain

+       Type: string

+ 

+       Default: ``None``

+ 

+       Email domain name that koji will append to usernames when creating email notifications.

+ 

+    NotifyOnSuccess

+       Type: boolean

+ 

+       Default: ``True``

+ 

+       Whether to send the task owner and package owner email or not on success.

+       This still goes to watchers.

+ 

+    DisableNotifications

+       Type: boolean

+ 

+       Default: ``False``

+ 

+       Disables all notifications

+ 

+ For more on notifications in Koji, see :ref:`notification-basics`

+ 

+ Resource limits

+ ^^^^^^^^^^^^^^^

+ If configured, the following resource limits are applied by the hub at startup.

+ Each value defaults to ``None``, meaning no limit is applied.

+ If given, the value should be either a single integer or a pair of integers separated by whitespace.

+ 

+ If a pair of integers is given, this sets both the soft and hard limits for the resource.

+ If a single integer is given, only the soft limit is set.

+ 

+ .. glossary::

+    RLIMIT_AS

+       Type: string

+ 

+       Default: ``None``

+ 

+       This is the maximum size of the process's virtual memory (address space).

+       The limit is specified in bytes, and is rounded down to the system page size.

+ 

+    RLIMIT_CORE

+       Type: string

+ 

+       Default: ``None``

+ 

+       This is the maximum size of a core file in bytes that the process may dump.

+       When 0, no core dump file are created. When nonzero, larger dumps are truncated to this size.

+ 

+    RLIMIT_CPU

+       Type: string

+ 

+       Default: ``None``

+ 

+       This is a limit, in seconds, on the amount of CPU time that the process can consume.

+ 

+    RLIMIT_DATA

+       Type: string

+ 

+       Default: ``None``

+ 

+       This is the maximum size of the process's data segment (initialized data,

+       uninitialized data, and heap). The limit is specified in bytes,

+       and is rounded down to the system page size.

+ 

+    RLIMIT_FSIZE

+       Type: string

+ 

+       Default: ``None``

+ 

+       This is the maximum size in bytes of files that the process may create.

+ 

+    RLIMIT_MEMLOCK

+       Type: string

+ 

+       Default: ``None``

+ 

+       This is the maximum number of bytes of memory that may be  locked into RAM.

+       This limit is in effect rounded down to the nearest multiple of the system page size.

+ 

+    RLIMIT_NOFILE

+       Type: string

+ 

+       Default: ``None``

+ 

+       This specifies a value one greater than the maximum file descriptor number that

+       can be opened by this process.

+ 

+    RLIMIT_NPROC

+       Type: string

+ 

+       Default: ``None``

+ 

+       This is a limit on the number of extant process (or, more precisely on Linux, threads)

+       for the real user ID of the  calling process.

+ 

+    RLIMIT_OFILE

+       Type: string

+ 

+       Default: ``None``

+ 

+       This specifies a value one greater than the maximum file descriptor number that

+       can be opened by this process. This limit was on BSD.

+ 

+    RLIMIT_RSS

+       Type: string

+ 

+       Default: ``None``

+ 

+       This is a limit (in bytes) on the process's resident set (the number of virtual pages resident in RAM).

+ 

+    RLIMIT_STACK

+       Type: string

+ 

+       Default: ``None``

+ 

+       This is the maximum size of the process stack, in bytes.

+ 

+ Additionally, the following options govern resource-related behavior.

+ 

+ .. glossary::

+    MemoryWarnThreshold

+       Type: int

+ 

+       Default: ``5000``

+ 

+       If memory consumption rises more than this value (in kilobytes) while handling a single

+       request, a warning will be emitted to the log

+ 

+    MaxRequestLength

+       Type: int

+ 

+       Default: ``4194304``

+ 

+       This sets the maximum request length that the hub will process.

+       If a longer request is encountered, the hub will stop reading it and return an error.

+ 

+ Extended features

+ ^^^^^^^^^^^^^^^^^

+ Koji includes limited support for building via Maven or under Windows.

+ 

+ .. glossary::

+    EnableMaven

+       Type: boolean

+ 

+       Default: ``False``

+ 

+       This option enables support for building with Maven.

+ 

+    EnableWin

+       Type: boolean

+ 

+       Default: ``False``

+ 

+       This option enables support for :doc:`Windows builds <winbuild>`.

+ 

+ Koji hub plugins

+ ^^^^^^^^^^^^^^^^

+ The hub supports plugins, which are loaded from the ``PluginPath`` directory.

+ 

+ .. glossary::

+    PluginPath

+       Type: string

+ 

+       Default: ``/usr/lib/koji-hub-plugins``

+ 

+       The path where plugins are found.

+ 

+    Plugins

+       Type: string

+ 

+       Default: ``''``

+ 

+       A space-separated list of plugins to load.

+       Each entry should be the name of a plugin file (without the ``.py``).

+       Only plugins from the configured ``PluginPath`` can be loaded.

+ 

+ Koji debugging

+ ^^^^^^^^^^^^^^

+ The following options are primarily intended for debugging Koji's behavior.

+ 

+ .. glossary::

+    KojiDebug

+       Type: boolean

+ 

+       Default: ``False``

+ 

+       If KojiDebug is on, the hub will be /very/ verbose and will report exception details to

+       clients for anticipated errors (i.e. koji's own exceptions -- subclasses of koji.GenericError).

+ 

+       This option is only intended for specialized debugging and should be left off in production

+       environments.

+ 

+    KojiTraceback

+       Type: string

+ 

+       Default: ``None``

+ 

+       This determines how much detail about exceptions is reported to the client (via faults).

+       The meaningful values are:

+ 

+       * normal - a basic traceback (format_exception)

+       * extended - an extended traceback (format_exc_plus)

+ 

+       If left unset, the default behavior is to omit the traceback and just report the error

+       class and message.

+ 

+       Note: the extended traceback is intended for debugging only and should NOT be used in production,

+       since it may contain sensitive information.

+ 

+    LogLevel

+       Type: string

+ 

+       Default: ``WARNING``

+ 

+       This option controls the log level the hub logs.

+       Koji uses the standard Python logging module and the standard log level names.

+ 

+       Setting multiple log levels for different parts of the hub code is possible.

+       The option is treated as a space-separated list log level directives, which

+       can be either a single log level name (sets the default log level) or a

+       logger:level pair (sets the log level for the given logger namespace).

+ 

+       For example, you could set:

+ 

+          ``LogLevel = INFO koji.db:DEBUG``

+ 

+       To see debug logging only for the db module.

+ 

+    LogFormat

+       Type:string

+ 

+       Default: ``%(asctime)s [%(levelname)s] m=%(method)s u=%(user_name)s p=%(process)s r=%(remoteaddr)s %(name)s: %(message)s``

+ 

+       This sets the log format string for log messages issued by the hub code.

+       In addition to the normal values available from the logging module, the hub's log formatter provides:

+ 

+       * method -- the method name for the call being processed

+       * user_id -- the id of the user making the call

+       * user_name -- the name of the user making the call

+       * session_id -- the session_id of the call

+       * callnum -- the callnum value for the session

+       * remoteaddr -- the ip address and port (colon separated) that the call is coming from

+ 

+ Hub Policy

+ ^^^^^^^^^^

+ .. glossary::

+    VerbosePolicy

+       Type: boolean

+ 

+       Default: ``False``

+ 

+       If VerbosePolicy (or KojiDebug) is on, 'policy violation' messages will report the

+       policy rule which caused the denial.

+ 

+    MissingPolicyOk

+       Type: boolean

+ 

+       Default: ``True``

+ 

+       If MissingPolicyOk is on, and a given policy is not defined, the policy check will return

+       'allow', otherwise such cases will result in 'deny'.

+ 

+ Koji outages options

+ ^^^^^^^^^^^^^^^^^^^^

+ These options are intended for planned outages.

+ 

+ .. glossary::

+    ServerOffline

+       Type: boolean

+ 

+       Default: ``False``

+ 

+       If ServerOffline is True, the server will always report a ServerOffline fault

+       (with OfflineMessage as the fault string).

+ 

+    OfflineMessage

+       Type: string

+ 

+       Default: ``None``

+ 

+       This controls the error message that is reported when ``ServerOffline`` is set.

+ 

+    LockOut

+       Type: boolean

+ 

+       Default: ``False``

+ 

+       If Lockout is True, the server will report a ServerOffline fault for most non-admin requests.

  

  Name verification

  ^^^^^^^^^^^^^^^^^
@@ -37,15 +507,27 @@ 

  Host names are listed in both groups because hosts always have an associated user entry.

  

  .. glossary::

-     MaxNameLengthInternal = 256

-         Set length of internal names. By default there is allowed length set up to 256.

-         When length is set up to 0, length verifying is disabled.

+    MaxNameLengthInternal

+       Type: string

+ 

+       Default: ``256``

+ 

+       Set length of internal names. By default there is allowed length set up to 256.

+       When length is set up to 0, length verifying is disabled.

+ 

+    RegexNameInternal

+       Type: string

+ 

+       Default: ``^[A-Za-z0-9/_.+-]+$``

+ 

+       Set regex for verify an internal names. When regex string is empty, verifying

+       is disabled.

+ 

+    RegexUserName = ^[A-Za-z0-9/_.@-]+$

+       Type: string

  

-     RegexNameInternal = ^[A-Za-z0-9/_.+-]+$

-         Set regex for verify an internal names. When regex string is empty, verifying

-         is disabled.

+       Default: ``^[A-Za-z0-9/_.@-]+$``

  

-     RegexUserName = ^[A-Za-z0-9/_.@-]+$

-         Set regex for verify a user name and kerberos. User name and kerberos have

-         in default set up allowed '@' and '/' chars on top of basic name regex

-         for internal names. When regex string is empty, verifying is disabled.

+       Set regex for verify a user name and kerberos. User name and kerberos have

+       in default set up allowed '@' and '/' chars on top of basic name regex

+       for internal names. When regex string is empty, verifying is disabled.

file modified
+1 -1
@@ -777,7 +777,7 @@ 

  ``/etc/koji-hub/hub.conf.d/secret.conf`` for sensitive values. Typical usecase

  for separate config is :doc:`policy <defining_hub_policies>` configuration file.

  

- Doc page about hub options in :doc:`Hub conf <hub_conf>`. (Currently in progress).

+ Doc page about hub options in :doc:`Hub conf <hub_conf>`.

  

  Authentication Configuration

  ----------------------------

@@ -148,6 +148,8 @@ 

  

      pk12util -d sql:$HOME/.pki/nssdb -i fedora-browser-cert.p12

  

+ .. _notification-basics:

+ 

  Notifications

  ^^^^^^^^^^^^^

  

Fixes: https://pagure.io/koji/issue/3073

Because PR 3028 isn't merged yet, in this PR are some duplicated things like basic info about this document, add this document to the index.rst. Based on which PR will be merged first, I will rebase second PR for correct contain without duplicated things.

Metadata Update from @tkopecek:
- Pull-request tagged with: doc

7 months ago

I'd like for this page to primarily be a listing of configuration options with data on each. The current version includes a lot of explanatory text outside of the options. I'd like to keep such content to a minimum.

A lot of the content here has been copied from the old server_howto doc. We need to be careful propagating that content as some of it could be inaccurate.

We've dropped a number of KRBV related options, and we should not document those.

Most of the config item headings here appear to be based on the example httpd file, e.g.

 DBName = koji

It's not 100% clear what the value after the = is meant to signify, but people are likely to assume this is the default, and many of the entries list the default incorrectly (e.g the dbname does not actually default to koji). I think we should be explicit and clearly the default value. Also, I think the heading should just be the name of the option with any other information on subsequent lines.

When I last looked at this, I ended up making a number of adjustments. That partial work is here:
https://pagure.io/fork/mikem/koji/commits/pr3098-updates

This probably needs a bit more cleanup. I keep switching back and forth about whether to include the Type field for the entries.

Side note -- I was curious how other projects format their configuration docs in sphinx. I found a number that use various sphinx extensions to provide .. confval:: markup, either by using the sphinx-toolbox package or simply including a similar extension in their conf.py file (sphinx itself does the latter for its own docs).

I'd rather not grow a dependency on sphinx-toolbox (doesn't seem to be in Fedora) and I'm not sure this is important enough to add custom code into conf.py, so I think the current approach of using .. glossary:: is fine.

rebased onto ba94b957ee1fa3073cf93b849f4521cdec1c00fc

5 months ago

rebased onto fb97e310bf74c8f244ece8b948dcfce5c60ad049

5 months ago

rebased onto f91845e

5 months ago

@mikem Updated. I merged documentation part related to limit of names also.

I am for us it with type of field for entries :) .

works for me, let's run with it :thumbsup:

Commit 850bea5 fixes this pull-request

Pull-Request has been merged by tkopecek

5 months ago

Metadata Update from @jcupova:
- Pull-request tagged with: no_qe

5 months ago