diff --git a/.github/allow-documented-unused.txt b/.github/allow-documented-unused.txt new file mode 100644 index 0000000000..a6721c547b --- /dev/null +++ b/.github/allow-documented-unused.txt @@ -0,0 +1,9 @@ +DB_URL +PLUGIN_AUTH_LDAP +PLUGIN_AUTH_OIDC +PLUGIN_FREEIPA +PLUGIN_IQUOTA +PLUGIN_LDAP_USER_SEARCH +PLUGIN_PROJECT_OPENLDAP +PLUGIN_SLURM +PLUGIN_XDMOD diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d87de0bc18..54d8b92827 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,3 +31,48 @@ jobs: - name: Run tests run: uv run coldfront test + + check_docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: apt install -y ripgrep + run: | + echo "set man-db/auto-update false" | sudo debconf-communicate + sudo dpkg-reconfigure man-db + sudo apt install -y ripgrep + # a setting "foo" exists if there is any use of `import_from_settings("foo")` or {% settings_value "foo" %} + # note about quotations: '\bsettings_value[ ]+["'"'"']([A-Z_]+)' -> \bsettings_value[ ]+["']([A-Z_]+) + # import_from_settings('foo') is not considered because ruff format ensures double quotes are used + # `grep .` filters out empty lines + - name: gather list of settings used + run: | + ( + rg -INU '\bimport_from_settings\([\s\n]*"([A-Z_]+)' -or '$1' . + rg -IN '\bsettings_value[ ]+["'"'"']([A-Z_]+)' -or '$1' . + ) | grep . | sort -u | tee -a /tmp/settings.txt + # an env var "foo" exists if there is any use of `ENV.bool("foo")` or `ENV.int("foo")` or `ENV.list("foo")` or ... + - name: gather list of environment variables used + run: rg -INU '\bENV\.[a-z]+\([\s\n]*"([A-Z_]+)' -or '$1' . | grep . | sort -u | tee /tmp/envvars.txt + # a setting or environment variable is documented if it is found in the leftmost column of a table in docs/pages/config.md + - name: gather list of settings and environment variables documented + run: rg '^\|[ ]*`?([A-Z_]{2,})' -or '$1' docs/pages/config.md | sort -u | tee /tmp/documented.txt + - name: check that all settings used are documented + run: | + if grep -vFx --file=/tmp/documented.txt /tmp/settings.txt; then + echo "the settings above must be added to the documentation!" + exit 1 + fi + - name: check that all environment variables used are documented + run: | + if grep -vFx --file=/tmp/documented.txt /tmp/envvars.txt; then + echo "the environment variables above must be added to the documentation!" + exit 1 + fi + - name: check that all settings and environment variables documented are used + run: | + if grep -vFx --file=/tmp/settings.txt --file=/tmp/envvars.txt --file=.github/allow-documented-unused.txt /tmp/documented.txt; then + echo "the environment variables above are documented but never used!" + echo "to silence this error for a specific variable, add it to the file '.github/allow-documented-unused.txt'." + exit 1 + fi diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ddc157a0b..c1585229af 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,3 +65,10 @@ If your code is failing linting checks but you you have a valid reason to leave You can also use Ruff to check formatting using `uv run ruff format --check` and automatically fix formatting errors with `uv run ruff format`. If your code is failing formatting checks but you have a valid reason to leave it unchanged, you can suppress warnings for a specific block of code by enclosing it with the comments `# fmt: off` and `# fmt: on`. These comments work at the statement level so placing them inside of expressions will not have any effect. + +#### Documentation + +All settings and environment variables used should be present in [docs/pages/config.md](docs/pages/config.md). +A "setting used" is the 1st argument to any `import_from_settings()` function call or `{% setting_value %}` jinja2 macro usage. +An "environment variable used" is the 1st argument to any `ENV` function call (ex: `ENV.bool()`) +Setting names and environment variable names should contain capital letters and underscores only. diff --git a/docs/pages/config.md b/docs/pages/config.md index 4806abee93..c1577037c5 100644 --- a/docs/pages/config.md +++ b/docs/pages/config.md @@ -62,60 +62,83 @@ $ COLDFRONT_ENV=coldfront.env coldfront runserver The following settings allow overriding basic ColdFront Django settings. For more advanced configuration use `local_settings.py`. -| Name | Description | -| :------------------------- |:-------------------------------------| -| ALLOWED_HOSTS | A list of strings representing the host/domain names that ColdFront can serve. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#allowed-hosts) | -| DEBUG | Turn on/off debug mode. Never deploy a site into production with DEBUG turned on. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#debug) | -| SECRET_KEY | This is used to provide cryptographic signing, and should be set to a unique, unpredictable value. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#secret-key). If you don't provide this one will be generated each time ColdFront starts. | -| LANGUAGE_CODE | A string representing the language code. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#language-code) -| TIME_ZONE | A string representing the time zone for this installation. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#std:setting-TIME_ZONE) | -| Q_CLUSTER_RETRY | The number of seconds Django Q broker will wait for a cluster to finish a task. [See here](https://django-q.readthedocs.io/en/latest/configure.html#retry) | -| Q_CLUSTER_TIMEOUT | The number of seconds a Django Q worker is allowed to spend on a task before it’s terminated. IMPORTANT NOTE: Q_CLUSTER_TIMEOUT must be less than Q_CLUSTER_RETRY. [See here](https://django-q.readthedocs.io/en/latest/configure.html#timeout) | -| SESSION_INACTIVITY_TIMEOUT | Seconds of inactivity after which sessions will expire (default 1hr). This value sets the `SESSION_COOKIE_AGE` and the session is saved on every request. [See here](https://docs.djangoproject.com/en/4.1/topics/http/sessions/#when-sessions-are-saved) | +| Name | Description | Has Setting | Has Environment Variable | +| :------------------------- |:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------|:-------------------------| +| ALLOWED_HOSTS | A list of strings representing the host/domain names that ColdFront can serve. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#allowed-hosts) | no | yes | +| DEBUG | Turn on/off debug mode. Never deploy a site into production with DEBUG turned on. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#debug) | no | yes | +| SECRET_KEY | This is used to provide cryptographic signing, and should be set to a unique, unpredictable value. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#secret-key). If you don't provide this one will be generated each time ColdFront starts. | no | yes | +| LANGUAGE_CODE | A string representing the language code. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#language-code) | no | yes | +| TIME_ZONE | A string representing the time zone for this installation. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#std:setting-TIME_ZONE) | no | yes | +| Q_CLUSTER_RETRY | The number of seconds Django Q broker will wait for a cluster to finish a task. [See here](https://django-q.readthedocs.io/en/latest/configure.html#retry) | no | yes | +| Q_CLUSTER_TIMEOUT | The number of seconds a Django Q worker is allowed to spend on a task before it’s terminated. IMPORTANT NOTE: Q_CLUSTER_TIMEOUT must be less than Q_CLUSTER_RETRY. [See here](https://django-q.readthedocs.io/en/latest/configure.html#timeout) | no | yes | +| SESSION_INACTIVITY_TIMEOUT | Seconds of inactivity after which sessions will expire (default 1hr). This value sets the `SESSION_COOKIE_AGE` and the session is saved on every request. [See here](https://docs.djangoproject.com/en/4.1/topics/http/sessions/#when-sessions-are-saved) | no | yes | ### Template settings -| Name | Description | -| :--------------------|:-------------------------------------| -| STATIC_ROOT | Path to the directory where collectstatic will collect static files for deployment. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#std:setting-STATIC_ROOT) | -| SITE_TEMPLATES | Path to a directory of custom templates. Add custom templates here. This path will be added to TEMPLATES DIRS. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#std:setting-TEMPLATES-DIRS) | -| SITE_STATIC | Path to a directory of custom static files. Add custom css here. This path will be added to STATICFILES_DIRS [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#std:setting-STATICFILES_DIRS) | +| Name | Description | Has Setting | Has Environment Variable | +| :--------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------|:-------------------------| +| STATIC_ROOT | Path to the directory where collectstatic will collect static files for deployment. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#std:setting-STATIC_ROOT) | no | yes | +| SITE_TEMPLATES | Path to a directory of custom templates. Add custom templates here. This path will be added to TEMPLATES DIRS. [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#std:setting-TEMPLATES-DIRS) | no | yes | +| SITE_STATIC | Path to a directory of custom static files. Add custom css here. This path will be added to STATICFILES_DIRS [See here](https://docs.djangoproject.com/en/3.1/ref/settings/#std:setting-STATICFILES_DIRS) | no | yes | ### ColdFront core settings The following settings are ColdFront specific settings related to the core application. -| Name | Description | -| :--------------------------------------|:-----------------------------------------------| -| CENTER_NAME | The display name of your center | -| CENTER_HELP_URL | The URL of your help ticketing system | -| CENTER_PROJECT_RENEWAL_HELP_URL | The URL of the article describing project renewals | -| CENTER_BASE_URL | The base URL of your center. | -| PROJECT_ENABLE_PROJECT_REVIEW | Enable or disable project reviews. Default True| -| ALLOCATION_ENABLE_ALLOCATION_RENEWAL | Enable or disable allocation renewals. Default True | -| ALLOCATION_DEFAULT_ALLOCATION_LENGTH | Default number of days an allocation is active for. Default 365 | -| ALLOCATION_ENABLE_CHANGE_REQUESTS_BY_DEFAULT | Enable or disable allocation change requests. Default True | -| ALLOCATION_CHANGE_REQUEST_EXTENSION_DAYS | List of days users can request extensions in an allocation change request. Default 30,60,90 | -| ALLOCATION_ACCOUNT_ENABLED | Allow user to select account name for allocation. Default False | -| ALLOCATION_RESOURCE_ORDERING | Controls the ordering of parent resources for an allocation (if allocation has multiple resources). Should be a list of field names suitable for Django QuerySet order_by method. Default is ['-is_allocatable', 'name']; i.e. prefer Resources with is_allocatable field set, ordered by name of the Resource.| -| ALLOCATION_EULA_ENABLE | Enable or disable requiring users to agree to EULA on allocations. Only applies to allocations using a resource with a defined 'eula' attribute. Default False| -| INVOICE_ENABLED | Enable or disable invoices. Default True | -| ONDEMAND_URL | The URL to your Open OnDemand installation | -| LOGIN_FAIL_MESSAGE | Custom message when user fails to login. Here you can paint a custom link to your user account portal | -| ENABLE_SU | Enable administrators to login as other users. Default True | -| RESEARCH_OUTPUT_ENABLE | Enable or disable research outputs. Default True | -| GRANT_ENABLE | Enable or disable grants. Default True | -| PUBLICATION_ENABLE | Enable or disable publications. Default True | -| PROJECT_CODE | Specifies a custom internal project identifier. Default False, provide string value to enable. Must be no longer than 10 - PROJECT_CODE_PADDING characters in length.| -| PROJECT_CODE_PADDING | Defines a optional padding value to be added before the Primary Key section of PROJECT_CODE. Default False, provide integer value to enable.| -| PROJECT_INSTITUTION_EMAIL_MAP | Defines a dictionary where PI domain email addresses are keys and their corresponding institutions are values. Default is False, provide key-value pairs to enable this feature.| +| Name | Description | Has Setting | Has Environment Variable | +|:---------------------------------------------|:------------------------------------------------------------------------------------------------------|:------------|:-------------------------| +| CENTER_NAME | The display name of your center | yes | yes | +| CENTER_HELP_URL | The URL of your help ticketing system | no | yes | +| CENTER_PROJECT_RENEWAL_HELP_URL | The URL of the article describing project renewals | yes | yes | +| CENTER_BASE_URL | The base URL of your center. | yes | yes | +| PROJECT_ENABLE_PROJECT_REVIEW | Enable or disable project reviews. Default True | yes | yes | +| ALLOCATION_ENABLE_ALLOCATION_RENEWAL | Enable or disable allocation renewals. Default True | yes | yes | +| ALLOCATION_DEFAULT_ALLOCATION_LENGTH | Default number of days an allocation is active for. Default 365 | yes | yes | +| ALLOCATION_ENABLE_CHANGE_REQUESTS_BY_DEFAULT | Enable or disable allocation change requests. Default True | yes | no | +| ALLOCATION_CHANGE_REQUEST_EXTENSION_DAYS | List of days users can request extensions in an allocation change request. Default 30,60,90 | yes | yes | +| ALLOCATION_ACCOUNT_ENABLED | Allow user to select account name for allocation. Default False | yes | yes | +| ALLOCATION_ACCOUNT_MAPPING | Mapping where each key is the name of a resource and each value is the name of the attribute where the account name will be stored in the allocation. Only applies when `ALLOCATION_ACCOUNT_ENABLE` is true. Default `{}` | yes | yes | +| ALLOCATION_RESOURCE_ORDERING | Controls the ordering of parent resources for an allocation (if allocation has multiple resources). Should be a list of field names suitable for Django QuerySet order_by method. Default is ['-is_allocatable', 'name']; i.e. prefer Resources with is_allocatable field set, ordered by name of the Resource. | yes | no | +| ALLOCATION_EULA_ENABLE | Enable or disable requiring users to agree to EULA on allocations. Only applies to allocations using a resource with a defined 'eula' attribute. Default False | yes | yes | +| ALLOCATION_ATTRIBUTE_VIEW_LIST | Names of allocation attributes which should be viewed as a list | yes | yes | +| ALLOCATION_FUNCS_ON_EXPIRE | Functions to be called when an allocation expires | yes | no | +| INVOICE_ENABLED | Enable or disable invoices. Default True | yes | yes | +| ONDEMAND_URL | The URL to your Open OnDemand installation | no | yes | +| LOGIN_FAIL_MESSAGE | Custom message when user fails to login. Here you can paint a custom link to your user account portal | no | yes | +| ENABLE_SU | Enable administrators to login as other users. Default True | no | yes | +| RESEARCH_OUTPUT_ENABLE | Enable or disable research outputs. Default True | no | yes | +| GRANT_ENABLE | Enable or disable grants. Default True | no | yes | +| PUBLICATION_ENABLE | Enable or disable publications. Default True | no | yes | +| PROJECT_CODE | Specifies a custom internal project identifier. Default False, provide string value to enable. Must be no longer than 10 - PROJECT_CODE_PADDING characters in length. | yes | yes | +| PROJECT_CODE_PADDING | Defines a optional padding value to be added before the Primary Key section of PROJECT_CODE. Default False, provide integer value to enable. | yes | yes | +| PROJECT_INSTITUTION_EMAIL_MAP | Defines a dictionary where PI domain email addresses are keys and their corresponding institutions are values. Default is False, provide key-value pairs to enable this feature. | yes | yes | +| ACCOUNT_CREATION_TEXT | | yes | yes | +| ADDITIONAL_USER_SEARCH_CLASSES | | yes | no | +| ADMIN_COMMENTS_SHOW_EMPTY | | no | yes | +| ALLOCATION_ENABLE_CHANGE_REQUESTS | | no | yes | +| BASE_DIR | | yes | no | +| COLDFRONT_CONFIG | | no | yes | +| COLDFRONT_ENV | | no | yes | +| INVOICE_DEFAULT_STATUS | | yes | yes | +| LOGOUT_REDIRECT_URL | | no | yes | +| PLUGIN_API | | no | yes | +| SYSMON_ENDPOINT | | no | yes | +| SYSMON_LINK | | no | yes | +| SYSMON_TITLE | | no | yes | +| SYSMON_XDMOD_LINK | | no | yes | +| SYSTEM_MONITOR_DISPLAY_MORE_STATUS_INFO_LINK | | yes | no | +| SYSTEM_MONITOR_DISPLAY_XDMOD_LINK | | yes | no | +| SYSTEM_MONITOR_ENDPOINT | | yes | no | +| SYSTEM_MONITOR_PANEL_TITLE | | yes | no | +| TEMPLATES | | yes | no | + ### Database settings The following settings configure the database server to use, if not set will default to using SQLite: -| Name | Description | -| :--------------------|:-------------------------------------| -| DB_URL | The database connection url string | +| Name | Description | Has Setting | Has Environment Variable | +| :--------------------|:-----------------------------------|:------------|:-------------------------| +| DB_URL | The database connection url string | no | yes | Examples: @@ -131,30 +154,32 @@ DB_URL=sqlite:////usr/share/coldfront/coldfront.db The following settings configure emails in ColdFront. By default email is disabled: -| Name | Description | -| :-------------------------------|:------------------------------------------| -| EMAIL_ENABLED | Enable/disable email. Default False | -| EMAIL_HOST | Hostname of smtp server | -| EMAIL_PORT | smtp port | -| EMAIL_HOST_USER | Username for smtp | -| EMAIL_HOST_PASSWORD | password for smtp | -| EMAIL_USE_TLS | Enable/disable tls. Default False | -| EMAIL_SENDER | Default sender email address | -| EMAIL_SUBJECT_PREFIX | Prefix to add to subject line | -| EMAIL_ADMIN_LIST | List of admin email addresses. | -| EMAIL_TICKET_SYSTEM_ADDRESS | Email address of ticketing system | -| EMAIL_DIRECTOR_EMAIL_ADDRESS | Email address for director | -| EMAIL_PROJECT_REVIEW_CONTACT | Email address of review contact | -| EMAIL_DEVELOPMENT_EMAIL_LIST | List of emails to send when in debug mode | -| EMAIL_OPT_OUT_INSTRUCTION_URL | URL of article regarding opt out | -| EMAIL_SIGNATURE | Email signature to add to outgoing emails | -| EMAIL_ALLOCATION_EXPIRING_NOTIFICATION_DAYS | List of days to send email notifications for expiring allocations. Default 7,14,30 | -| EMAIL_ADMINS_ON_ALLOCATION_EXPIRE | Setting this to True will send a daily email notification to administrators with a list of allocations that have expired that day. | -| EMAIL_ALLOCATION_EULA_REMINDERS | Enable/Disable EULA reminders. Default False | -| EMAIL_ALLOCATION_EULA_IGNORE_OPT_OUT | Ignore user email settings and always send EULA related emails. Default False | -| EMAIL_ALLOCATION_EULA_CONFIRMATIONS | Enable/Disable email notifications when a EULA is accepted or declined. Default False | -| EMAIL_ALLOCATION_EULA_CONFIRMATIONS_CC_MANAGERS | CC project managers on eula notification emails (requires EMAIL_ALLOCATION_EULA_CONFIRMATIONS to be enabled). Default False | -| EMAIL_ALLOCATION_EULA_INCLUDE_ACCEPTED_EULA | Include copy of EULA in email notifications for accepted EULAs. Default False | +| Name | Description | Has Setting | Has Environment Variable | +| :-----------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------|:------------|:-------------------------| +| EMAIL_ENABLED | Enable/disable email. Default False | yes | yes | +| EMAIL_HOST | Hostname of smtp server | no | yes | +| EMAIL_PORT | smtp port | no | yes | +| EMAIL_HOST_USER | Username for smtp | no | yes | +| EMAIL_HOST_PASSWORD | password for smtp | no | yes | +| EMAIL_USE_TLS | Enable/disable tls. Default False | no | yes | +| EMAIL_SENDER | Default sender email address | yes | yes | +| EMAIL_SUBJECT_PREFIX | Prefix to add to subject line | yes | yes | +| EMAIL_ADMIN_LIST | List of admin email addresses. | yes | yes | +| EMAIL_TICKET_SYSTEM_ADDRESS | Email address of ticketing system | yes | yes | +| EMAIL_DIRECTOR_EMAIL_ADDRESS | Email address for director | yes | yes | +| EMAIL_PROJECT_REVIEW_CONTACT | Email address of review contact | no | yes | +| EMAIL_DEVELOPMENT_EMAIL_LIST | List of emails to send when in debug mode | yes | yes | +| EMAIL_OPT_OUT_INSTRUCTION_URL | URL of article regarding opt out | yes | yes | +| EMAIL_SIGNATURE | Email signature to add to outgoing emails | yes | yes | +| EMAIL_ALLOCATION_EXPIRING_NOTIFICATION_DAYS | List of days to send email notifications for expiring allocations. Default 7,14,30 | yes | yes | +| EMAIL_ADMINS_ON_ALLOCATION_EXPIRE | Setting this to True will send a daily email notification to administrators with a list of allocations that have expired that day. | yes | yes | +| EMAIL_ALLOCATION_EULA_REMINDERS | Enable/Disable EULA reminders. Default False | no | yes | +| EMAIL_ALLOCATION_EULA_IGNORE_OPT_OUT | Ignore user email settings and always send EULA related emails. Default False | yes | yes | +| EMAIL_ALLOCATION_EULA_CONFIRMATIONS | Enable/Disable email notifications when a EULA is accepted or declined. Default False | yes | yes | +| EMAIL_ALLOCATION_EULA_CONFIRMATIONS_CC_MANAGERS | CC project managers on eula notification emails (requires EMAIL_ALLOCATION_EULA_CONFIRMATIONS to be enabled). Default False | yes | yes | +| EMAIL_ALLOCATION_EULA_INCLUDE_ACCEPTED_EULA | Include copy of EULA in email notifications for accepted EULAs. Default False | yes | yes | +| EMAIL_TIMEOUT | | no | yes | +| EMAIL_DIRECTOR_PENDING_PROJECT_REVIEW_EMAIL | | yes | no | ### Plugin settings For more info on [ColdFront plugins](plugin/existing_plugins.md) (Django apps) @@ -171,18 +196,19 @@ For more info on [ColdFront plugins](plugin/existing_plugins.md) (Django apps) global OS ldap config, `/etc/{ldap,openldap}/ldap.conf` and within `TLS_CACERT` -| Name | Description | -| :---------------------------|:----------------------------------------| -| PLUGIN_AUTH_LDAP | Enable LDAP Authentication Backend. Default False | -| AUTH_LDAP_SERVER_URI | URI of LDAP server | -| AUTH_LDAP_START_TLS | Enable/disable start tls. Default True | -| AUTH_LDAP_BIND_DN | The distinguished name to use when binding to the LDAP server | -| AUTH_LDAP_BIND_PASSWORD | The password to use AUTH_LDAP_BIND_DN | -| AUTH_LDAP_USER_SEARCH_BASE | User search base dn | -| AUTH_LDAP_GROUP_SEARCH_BASE | Group search base dn | -| AUTH_COLDFRONT_LDAP_SEARCH_SCOPE | The search scope for Coldfront authentication. Options: SUBTREE or default (ONELEVEL) | -| AUTH_LDAP_MIRROR_GROUPS | Enable/disable mirroring of groups. Default True | -| AUTH_LDAP_BIND_AS_AUTHENTICATING_USER | Authentication will leave the LDAP connection bound as the authenticating user, rather than forcing it to re-bind. Default False | +| Name | Description | Has Setting | Has Environment Variable | +| :-------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------|:------------|:-------------------------| +| PLUGIN_AUTH_LDAP | Enable LDAP Authentication Backend. Default False | ? | ? | +| AUTH_LDAP_SERVER_URI | URI of LDAP server | no | yes | +| AUTH_LDAP_START_TLS | Enable/disable start tls. Default True | no | yes | +| AUTH_LDAP_BIND_DN | The distinguished name to use when binding to the LDAP server | no | yes | +| AUTH_LDAP_BIND_PASSWORD | The password to use AUTH_LDAP_BIND_DN | no | yes | +| AUTH_LDAP_USER_SEARCH_BASE | User search base dn | no | yes | +| AUTH_LDAP_GROUP_SEARCH_BASE | Group search base dn | no | yes | +| AUTH_COLDFRONT_LDAP_SEARCH_SCOPE | The search scope for Coldfront authentication. Options: SUBTREE or default (ONELEVEL) | no | yes | +| AUTH_LDAP_MIRROR_GROUPS | Enable/disable mirroring of groups. Default True | no | yes | +| AUTH_LDAP_BIND_AS_AUTHENTICATING_USER | Authentication will leave the LDAP connection bound as the authenticating user, rather than forcing it to re-bind. Default False | no | yes | +| AUTH_LDAP_USER_ATTR_MAP | | no | yes | #### OpenID Connect Auth @@ -197,18 +223,18 @@ For more info on [ColdFront plugins](plugin/existing_plugins.md) (Django apps) authentication process. You must use `SESSION_COOKIE_SAMESITE="Lax"` in your settings for authentication to work correctly. -| Name | Description | -| :------------------------------|:-------------------------------------| -| PLUGIN_AUTH_OIDC | Enable OpenID Connect Authentication Backend. Default False | -| OIDC_OP_JWKS_ENDPOINT | URL of JWKS endpoint | -| OIDC_RP_SIGN_ALGO | Signature algorithm | -| OIDC_RP_CLIENT_ID | Client ID | -| OIDC_RP_CLIENT_SECRET | Client secret | -| OIDC_OP_AUTHORIZATION_ENDPOINT | OAuth2 authorization endpoint | -| OIDC_OP_TOKEN_ENDPOINT | OAuth2 token endpoint | -| OIDC_OP_USER_ENDPOINT | OAuth2 userinfo endpoint | -| OIDC_VERIFY_SSL | Verify ssl Default True | -| OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS | Token lifetime in seconds. Default 3600 | +| Name | Description | Has Setting | Has Environment Variable | +| :----------------------------------|:------------------------------------------------------------|:------------|:-------------------------| +| PLUGIN_AUTH_OIDC | Enable OpenID Connect Authentication Backend. Default False | ? | ? | +| OIDC_OP_JWKS_ENDPOINT | URL of JWKS endpoint | no | yes | +| OIDC_RP_SIGN_ALGO | Signature algorithm | no | yes | +| OIDC_RP_CLIENT_ID | Client ID | no | yes | +| OIDC_RP_CLIENT_SECRET | Client secret | no | yes | +| OIDC_OP_AUTHORIZATION_ENDPOINT | OAuth2 authorization endpoint | no | yes | +| OIDC_OP_TOKEN_ENDPOINT | OAuth2 token endpoint | no | yes | +| OIDC_OP_USER_ENDPOINT | OAuth2 userinfo endpoint | no | yes | +| OIDC_VERIFY_SSL | Verify ssl Default True | no | yes | +| OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS | Token lifetime in seconds. Default 3600 | no | yes | #### Mokey @@ -216,46 +242,64 @@ For more info on [ColdFront plugins](plugin/existing_plugins.md) (Django apps) Mokey depends on the OpenID Connect plugin above. You must also enable the OpenID Connect plugin via `PLUGIN_AUTH_OIDC=True`. -| Name | Description | -| :--------------------|:-------------------------------------| -| PLUGIN_MOKEY | Enable Mokey/Hydra OpenID Connect Authentication Backend. Default False| +| Name | Description | Has Setting | Has Environment Variable | +| :-------------------------|:------------------------------------------------------------------------|:------------|:-------------------------| +| PLUGIN_MOKEY | Enable Mokey/Hydra OpenID Connect Authentication Backend. Default False | no | yes | +| MOKEY_OIDC_ALLOWED_GROUPS | | yes | no | +| MOKEY_OIDC_DENY_GROUPS | | yes | no | +| MOKEY_OIDC_PI_GROUP | | yes | yes | #### Slurm -| Name | Description | -| :---------------------|:-------------------------------------| -| PLUGIN_SLURM | Enable Slurm integration. Default False | -| SLURM_SACCTMGR_PATH | Path to sacctmgr command. Default `/usr/bin/sacctmgr` | -| SLURM_NOOP | Enable/disable noop. Default False | -| SLURM_IGNORE_USERS | List of user accounts to ignore when generating Slurm associations | -| SLURM_IGNORE_ACCOUNTS | List of Slurm accounts to ignore when generating Slurm associations | +| Name | Description | Has Setting | Has Environment Variable | +| :-------------------------------|:--------------------------------------------------------------------|:------------|:-------------------------| +| PLUGIN_SLURM | Enable Slurm integration. Default False | ? | ? | +| SLURM_SACCTMGR_PATH | Path to sacctmgr command. Default `/usr/bin/sacctmgr` | yes | yes | +| SLURM_NOOP | Enable/disable noop. Default False | yes | yes | +| SLURM_IGNORE_USERS | List of user accounts to ignore when generating Slurm associations | yes | yes | +| SLURM_IGNORE_ACCOUNTS | List of Slurm accounts to ignore when generating Slurm associations | yes | yes | +| SLURM_ACCOUNT_ATTRIBUTE_NAME | Internal use only | yes | no | +| SLURM_CLUSTER_ATTRIBUTE_NAME | Internal use only | yes | no | +| SLURM_IGNORE_CLUSTERS | Internal use only | yes | no | +| SLURM_SPECS_ATTRIBUTE_NAME | Internal use only | yes | no | +| SLURM_USER_SPECS_ATTRIBUTE_NAME | Internal use only | yes | no | #### XDMoD -| Name | Description | -| :--------------------|:----------------------------------------| -| PLUGIN_XDMOD | Enable XDMoD integration. Default False | -| XDMOD_API_URL | URL to XDMoD API | +| Name | Description | Has Setting | Has Environment Variable | +| :------------------------------------|:----------------------------------------|:------------|:-------------------------| +| PLUGIN_XDMOD | Enable XDMoD integration. Default False | ? | ? | +| XDMOD_API_URL | URL to XDMoD API | yes | yes | +| XDMOD_ACC_HOURS_ATTRIBUTE_NAME | Internal use only | yes | no | +| XDMOD_ACCOUNT_ATTRIBUTE_NAME | Internal use only | yes | no | +| XDMOD_CLOUD_CORE_TIME_ATTRIBUTE_NAME | Internal use only | yes | no | +| XDMOD_CLOUD_PROJECT_ATTRIBUTE_NAME | Internal use only | yes | no | +| XDMOD_CPU_HOURS_ATTRIBUTE_NAME | Internal use only | yes | no | +| XDMOD_RESOURCE_ATTRIBUTE_NAME | Internal use only | yes | no | +| XDMOD_STORAGE_ATTRIBUTE_NAME | Internal use only | yes | no | +| XDMOD_STORAGE_GROUP_ATTRIBUTE_NAME | Internal use only | yes | no | #### FreeIPA -| Name | Description | -| :------------------------|:------------------------------------------| -| PLUGIN_FREEIPA | Enable FreeIPA integration. Default False | -| FREEIPA_KTNAME | Path to keytab file | -| FREEIPA_SERVER | Hostname of FreeIPA server | -| FREEIPA_USER_SEARCH_BASE | User search base dn | -| FREEIPA_ENABLE_SIGNALS | Enable/Disable signals. Default False | +| Name | Description | Has Setting | Has Environment Variable | +| :----------------------------|:------------------------------------------|:------------|:-------------------------| +| PLUGIN_FREEIPA | Enable FreeIPA integration. Default False | ? | ? | +| FREEIPA_KTNAME | Path to keytab file | yes | yes | +| FREEIPA_SERVER | Hostname of FreeIPA server | yes | yes | +| FREEIPA_USER_SEARCH_BASE | User search base dn | yes | yes | +| FREEIPA_ENABLE_SIGNALS | Enable/Disable signals. Default False | yes | no | +| FREEIPA_GROUP_ATTRIBUTE_NAME | Internal use only | yes | no | +| FREEIPA_NOOP | Internal use only | yes | no | #### iquota -| Name | Description | -| :---------------|:-----------------------------------------| -| PLUGIN_IQUOTA | Enable iquota integration. Default False | -| IQUOTA_KEYTAB | Path to keytab file | -| IQUOTA_CA_CERT | Path to ca cert | -| IQUOTA_API_HOST | Hostname of iquota server | -| IQUOTA_API_PORT | Port of iquota server | +| Name | Description | Has Setting | Has Environment Variable | +| :---------------|:-----------------------------------------|:------------|:-------------------------| +| PLUGIN_IQUOTA | Enable iquota integration. Default False | ? | ? | +| IQUOTA_KEYTAB | Path to keytab file | yes | yes | +| IQUOTA_CA_CERT | Path to ca cert | yes | yes | +| IQUOTA_API_HOST | Hostname of iquota server | yes | yes | +| IQUOTA_API_PORT | Port of iquota server | yes | yes | #### LDAP User Search @@ -269,20 +313,62 @@ exist in your backend LDAP to show up in the ColdFront user search. $ pip install ldap3 ``` -| Name | Description | -| :---------------------------|:----------------------------------------| -| PLUGIN_LDAP_USER_SEARCH | Enable LDAP User Search. Default False | -| LDAP_USER_SEARCH_SERVER_URI | URI of LDAP server | -| LDAP_USER_SEARCH_BIND_DN | The distinguished name to use when binding to the LDAP server | -| LDAP_USER_SEARCH_BIND_PASSWORD | The password to use LDAP_USER_SEARCH_BIND_DN | -| LDAP_USER_SEARCH_BASE | User search base dn | -| LDAP_USER_SEARCH_CONNECT_TIMEOUT | Time in seconds to wait before timing out. Default 2.5 | -| LDAP_USER_SEARCH_USE_SSL | Whether to use ssl when connecting to LDAP server. Default True | -| LDAP_USER_SEARCH_USE_TLS | Whether to use tls when connecting to LDAP server. Default False | -| LDAP_USER_SEARCH_PRIV_KEY_FILE | Path to the private key file. | -| LDAP_USER_SEARCH_CERT_FILE | Path to the certificate file. | -| LDAP_USER_SEARCH_CACERT_FILE | Path to the CA cert file. | -| LDAP_USER_SEARCH_CERT_VALIDATE_MODE | Whether to require/validate certs. If 'required', certs are required and validated. If 'optional', certs are optional but validated if provided. If 'none' (the default) certs are ignored. | +| Name | Description | Has Setting | Has Environment Variable | +| :-----------------------------------|:-----------------------------------------------------------------|:------------|:-------------------------| +| PLUGIN_LDAP_USER_SEARCH | Enable LDAP User Search. Default False | ? | ? | +| LDAP_USER_SEARCH_SERVER_URI | URI of LDAP server | yes | yes | +| LDAP_USER_SEARCH_BIND_DN | The distinguished name to use when binding to the LDAP server | yes | yes | +| LDAP_USER_SEARCH_BIND_PASSWORD | The password to use LDAP_USER_SEARCH_BIND_DN | yes | yes | +| LDAP_USER_SEARCH_BASE | User search base dn | yes | yes | +| LDAP_USER_SEARCH_CONNECT_TIMEOUT | Time in seconds to wait before timing out. Default 2.5 | yes | yes | +| LDAP_USER_SEARCH_USE_SSL | Whether to use ssl when connecting to LDAP server. Default True | yes | yes | +| LDAP_USER_SEARCH_USE_TLS | Whether to use tls when connecting to LDAP server. Default False | yes | yes | +| LDAP_USER_SEARCH_PRIV_KEY_FILE | Path to the private key file. | yes | yes | +| LDAP_USER_SEARCH_CERT_FILE | Path to the certificate file. | yes | yes | +| LDAP_USER_SEARCH_CACERT_FILE | Path to the CA cert file. | yes | yes | +| LDAP_USER_SEARCH_CERT_VALIDATE_MODE | Whether to require/validate certs. If 'required', certs are required and validated. If 'optional', certs are optional but validated if provided. If 'none' (the default) certs are ignored. | yes | yes | +| LDAP_USER_SEARCH_ATTRIBUTE_MAP | Internal use only | yes | no | +| LDAP_USER_SEARCH_MAPPING_CALLBACK | Internal use only | yes | no | +| LDAP_USER_SEARCH_SASL_CREDENTIALS | Internal use only | yes | no | +| LDAP_USER_SEARCH_SASL_MECHANISM | Internal use only | yes | no | +| LDAP_USER_SEARCH_USERNAME_ONLY_ATTR | Internal use only | yes | no | + +#### Project OpenLDAP + +This plugin allows for projects and project membership to be synced to an OpenLDAP server. +See `coldfront/coldfront/plugins/project_openldap/README.md` in the source code for more detailed information. + +| Option | Description | Has Setting | Has Environment Variable | +| :-------------------------------------------|:-------------------------------------------------------------------------------------|:------------|:-------------------------| +| `PLUGIN_PROJECT_OPENLDAP` | Enable the plugin, required to be set as True (bool). | yes | yes | +| `PROJECT_OPENLDAP_GID_START` | Starting value for project gidNumbers, requires an integer. | yes | yes | +| `PROJECT_OPENLDAP_SERVER_URI` | The URI of the OpenLDAP instance, requires a string URI. | yes | yes | +| `PROJECT_OPENLDAP_OU` | The OU where projects will be written, requires a string DN of OU. | yes | yes | +| `PROJECT_OPENLDAP_BIND_USER` | DN of bind user. | yes | yes | +| `PROJECT_OPENLDAP_BIND_PASSWORD` | The password for the bind user, requires a string. | yes | yes | +| `PROJECT_OPENLDAP_REMOVE_PROJECT` | Required to take action upon archive (action) of a project. Default True (bool). | yes | yes | +| `PROJECT_OPENLDAP_CONNECT_TIMEOUT` | Connection timeout. | yes | yes | +| `PROJECT_OPENLDAP_USE_SSL` | Use SSL. | yes | yes | +| `PROJECT_OPENLDAP_USE_TLS` | Enable Tls. | yes | yes | +| `PROJECT_OPENLDAP_PRIV_KEY_FILE` | Tls Private key. | yes | yes | +| `PROJECT_OPENLDAP_CERT_FILE` | Tls Certificate file. | yes | yes | +| `PROJECT_OPENLDAP_CACERT_FILE` | Tls CA certificate file. | yes | yes | +| `PROJECT_OPENLDAP_ARCHIVE_OU` | Destination OU for archived projects. | yes | yes | +| `PROJECT_OPENLDAP_DESCRIPTION_TITLE_LENGTH` | Truncates the project title before inserting it into the description LDAP attribute. | yes | yes | +| `PROJECT_OPENLDAP_EXCLUDE_USERS` | Exclude users from sync command. | yes | yes | + +#### Auto Compute Allocation + +| Option | Description | Has Setting | Has Environment Variable | +| :---------------------------------------------|:------------|:------------|:-------------------------| +| AUTO_COMPUTE_ALLOCATION_CHANGEABLE | | yes | yes | +| AUTO_COMPUTE_ALLOCATION_CLUSTERS | | yes | yes | +| AUTO_COMPUTE_ALLOCATION_CORE_HOURS | | yes | yes | +| AUTO_COMPUTE_ALLOCATION_CORE_HOURS_TRAINING | | yes | yes | +| AUTO_COMPUTE_ALLOCATION_DESCRIPTION | | yes | yes | +| AUTO_COMPUTE_ALLOCATION_END_DELTA | | yes | yes | +| AUTO_COMPUTE_ALLOCATION_FAIRSHARE_INSTITUTION | | yes | yes | +| AUTO_COMPUTE_ALLOCATION_LOCKED | | yes | yes | ## Advanced Configuration