diff --git a/docs/_static/env-vars/frontend.yaml b/docs/_static/env-vars/frontend.yaml index 01d919f6..41cc80b9 100644 --- a/docs/_static/env-vars/frontend.yaml +++ b/docs/_static/env-vars/frontend.yaml @@ -161,6 +161,6 @@ password_policy: min_digits: 1 min_special_characters: 1 banned_passwords_list: "" -configurable_notifications: false +configurable_notifications: true groupware: enabled: false diff --git a/docs/_static/env-vars/frontend_configvars.md b/docs/_static/env-vars/frontend_configvars.md index 3878fc35..e4c147f9 100644 --- a/docs/_static/env-vars/frontend_configvars.md +++ b/docs/_static/env-vars/frontend_configvars.md @@ -1,5 +1,5 @@ -2026-09-01-12-00-11 +2026-09-04-00-08-14 ## Deprecation Notice @@ -132,5 +132,5 @@ |`OC_PASSWORD_POLICY_MIN_DIGITS`
`FRONTEND_PASSWORD_POLICY_MIN_DIGITS`| 1.0.0 |int|`Define the minimum number of digits. Defaults to 1 if not set.`|`"1"`| |`OC_PASSWORD_POLICY_MIN_SPECIAL_CHARACTERS`
`FRONTEND_PASSWORD_POLICY_MIN_SPECIAL_CHARACTERS`| 1.0.0 |int|`Define the minimum number of characters from the special characters list to be present. Defaults to 1 if not set.`|`"1"`| |`OC_PASSWORD_POLICY_BANNED_PASSWORDS_LIST`
`FRONTEND_PASSWORD_POLICY_BANNED_PASSWORDS_LIST`| 1.0.0 |string|`Path to the 'banned passwords list' file. This only impacts public link password validation. See the documentation for more details.`|`""`| -|`FRONTEND_CONFIGURABLE_NOTIFICATIONS`| 1.0.0 |bool|`Allow configuring notifications via web client.`|`"false"`| +|`FRONTEND_CONFIGURABLE_NOTIFICATIONS`| 1.0.0 |bool|`Allow configuring notifications via web client.`|`"true"`| |`FRONTEND_GROUPWARE_ENABLED`| 3.7.0 |bool|`Enable groupware features. Defaults to false.`|`"false"`| diff --git a/docs/_static/env-vars/global_configvars.md b/docs/_static/env-vars/global_configvars.md index 7ce21d1e..62e0be3f 100644 --- a/docs/_static/env-vars/global_configvars.md +++ b/docs/_static/env-vars/global_configvars.md @@ -7,24 +7,24 @@ | `IDM_CREATE_DEMO_USERS` | 1.0.0 | bool | Flag to enable or disable the creation of the demo users. | "false" | | `OC_ADMIN_USER_ID` | 1.0.0 | string | ID of the user that should receive admin privileges. Consider that the UUID can be encoded in some LDAP deployment configurations like in .ldif files. These need to be decoded beforehand. | "" | | `OC_ASYNC_UPLOADS` | 1.0.0 | bool | Enable asynchronous file uploads. | "true" | -| `OC_CACHE_AUTH_PASSWORD` | 1.0.0 | string | The password to use for authentication. Only applies when using the 'nats-js-kv' store type. | "" | -| `OC_CACHE_AUTH_USERNAME` | 1.0.0 | string | The username to use for authentication. Only applies when using the 'nats-js-kv' store type. | "" | -| `OC_CACHE_DATABASE` | 1.0.0 | string | The database name the configured store should use. | "cache-stat" | -| `OC_CACHE_DISABLE_PERSISTENCE` | 1.0.0 | bool | Disable persistence of the cache. Only applies when using the 'nats-js-kv' store type. Defaults to false. | "false" | +| `OC_CACHE_AUTH_PASSWORD` | 1.0.0 | string | The password to authenticate with the cache. Only applies when store type 'nats-js-kv' is configured. | "" | +| `OC_CACHE_AUTH_USERNAME` | 1.0.0 | string | The username to authenticate with the cache. Only applies when store type 'nats-js-kv' is configured. | "" | +| `OC_CACHE_DATABASE` | 1.0.0 | string | The database name the configured store should use. | "cache-userinfo" | +| `OC_CACHE_DISABLE_PERSISTENCE` | 1.0.0 | bool | Disables persistence of the cache. Only applies when store type 'nats-js-kv' is configured. Defaults to false. | "false" | | `OC_CACHE_ENABLE_TLS` | 7.3.0 | bool | Enable TLS for the connection to file metadata cache. | "false" | | `OC_CACHE_STORE` | 1.0.0 | string | The type of the cache store. Supported values are: 'memory', 'redis-sentinel', 'nats-js-kv', 'noop'. See the text description for details. | "memory" | | `OC_CACHE_STORE_NODES` | 1.0.0 | []string | A list of nodes to access the configured store. This has no effect when 'memory' store is configured. Note that the behaviour how nodes are used is dependent on the library of the configured store. See the Environment Variable Types description for more details. | "[127.0.0.1:9233]" | | `OC_CACHE_TLS_INSECURE` | 7.3.0 | bool | Whether to verify the server TLS certificates. | "false" | -| `OC_CACHE_TLS_ROOT_CA_CERTIFICATE` | 7.3.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided FRONTEND_OCS_STAT_CACHE_TLS_INSECURE will be seen as false. | "" | -| `OC_CACHE_TTL` | 1.0.0 | Duration | Default time to live for user info in the cache. Only applied when access tokens has no expiration. See the Environment Variable Types description for more details. | "5m0s" | +| `OC_CACHE_TLS_ROOT_CA_CERTIFICATE` | 7.3.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided PROXY_OIDC_USERINFO_CACHE_TLS_INSECURE will be seen as false. | "" | +| `OC_CACHE_TTL` | 1.0.0 | Duration | Default time to live for user info in the user info cache. Only applied when access tokens has no expiration. See the Environment Variable Types description for more details. | "10s" | | `OC_CORS_ALLOW_CREDENTIALS` | 1.0.0 | bool | Allow credentials for CORS.See following chapter for more details: *Access-Control-Allow-Credentials* at \https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials. | "true" | | `OC_CORS_ALLOW_HEADERS` | 1.0.0 | []string | A list of allowed CORS headers. See following chapter for more details: *Access-Control-Request-Headers* at \https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Headers. See the Environment Variable Types description for more details. | "[Authorization Origin Content-Type Accept X-Requested-With X-Request-Id Ocs-Apirequest]" | -| `OC_CORS_ALLOW_METHODS` | 1.0.0 | []string | A list of allowed CORS methods. See following chapter for more details: *Access-Control-Request-Method* at \https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method. See the Environment Variable Types description for more details. | "[GET]" | +| `OC_CORS_ALLOW_METHODS` | 1.0.0 | []string | A list of allowed CORS methods. See following chapter for more details: *Access-Control-Request-Method* at \https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method. See the Environment Variable Types description for more details. | "[GET POST DELETE]" | | `OC_CORS_ALLOW_ORIGINS` | 1.0.0 | []string | A list of allowed CORS origins. See following chapter for more details: *Access-Control-Allow-Origin* at \https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin. See the Environment Variable Types description for more details. | "[*]" | | `OC_DECOMPOSEDFS_PROPAGATOR` | 1.0.0 | string | The propagator used for decomposedfs. At the moment, only 'sync' is fully supported, 'async' is available as an experimental option. | "sync" | -| `OC_DEFAULT_LANGUAGE` | 1.0.0 | string | The default language used by services and the WebUI. If not defined, English will be used as default. See the documentation for more details. | "en" | +| `OC_DEFAULT_LANGUAGE` | 1.0.0 | string | The default language used by services and the WebUI. If not defined, English will be used as default. See the documentation for more details. | "" | | `OC_DISABLE_VERSIONING` | 1.0.0 | bool | Disables versioning of files. When set to true, new uploads with the same filename will overwrite existing files instead of creating a new version. | "false" | -| `OC_ENABLE_OCM` | 1.0.0 | bool | Changing this value is NOT supported. Enables support for incoming federated sharing for clients. The backend behaviour is not changed. | "false" | +| `OC_ENABLE_OCM` | 1.0.0 | bool | Include OCM sharees when listing users. | "false" | | `OC_EVENTS_AUTH_PASSWORD` | 1.0.0 | string | The password to authenticate with the events broker. The events broker is the OpenCloud service which receives and delivers events between the services. | "" | | `OC_EVENTS_AUTH_USERNAME` | 1.0.0 | string | The username to authenticate with the events broker. The events broker is the OpenCloud service which receives and delivers events between the services. | "" | | `OC_EVENTS_CLUSTER` | 1.0.0 | string | The clusterID of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture. Mandatory when using NATS as event system. | "opencloud-cluster" | @@ -42,48 +42,48 @@ | `OC_INSECURE` | 1.0.0 | bool | Whether to verify the server TLS certificates. | "false" | | `OC_JWT_SECRET` | 1.0.0 | string | The secret to mint and validate jwt tokens. | "" | | `OC_KEYCLOAK_BASE_PATH` | 1.0.0 | string | The URL to access keycloak. | "" | -| `OC_KEYCLOAK_CLIENT_ID` | 1.0.0 | string | The client ID to authenticate with keycloak. | "" | +| `OC_KEYCLOAK_CLIENT_ID` | 1.0.0 | string | The client id to authenticate with keycloak. | "" | | `OC_KEYCLOAK_CLIENT_REALM` | 1.0.0 | string | The realm the client is defined in. | "" | | `OC_KEYCLOAK_CLIENT_SECRET` | 1.0.0 | string | The client secret to use in authentication. | "" | | `OC_KEYCLOAK_INSECURE_SKIP_VERIFY` | 1.0.0 | bool | Disable TLS certificate validation for Keycloak connections. Do not set this in production environments. | "false" | | `OC_KEYCLOAK_USER_REALM` | 1.0.0 | string | The realm users are defined. | "" | -| `OC_LDAP_BIND_DN` | 1.0.0 | string | LDAP DN to use for simple bind authentication with the target LDAP server. | "uid=idp,ou=sysusers,o=libregraph-idm" | +| `OC_LDAP_BIND_DN` | 1.0.0 | string | LDAP DN to use for simple bind authentication with the target LDAP server. | "uid=reva,ou=sysusers,o=libregraph-idm" | | `OC_LDAP_BIND_PASSWORD` | 1.0.0 | string | Password to use for authenticating the 'bind_dn'. | "" | -| `OC_LDAP_CACERT` | 1.0.0 | string | Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the LDAP service. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idp. | "" | +| `OC_LDAP_CACERT` | 1.0.0 | string | Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the LDAP service. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idm. | "" | | `OC_LDAP_DISABLED_USERS_GROUP_DN` | 1.0.0 | string | The distinguished name of the group to which added users will be classified as disabled when 'disable_user_mechanism' is set to 'group'. | "cn=DisabledUsersGroup,ou=groups,o=libregraph-idm" | | `OC_LDAP_DISABLE_USER_MECHANISM` | 1.0.0 | string | An option to control the behavior for disabling users. Valid options are 'none', 'attribute' and 'group'. If set to 'group', disabling a user via API will add the user to the configured group for disabled users, if set to 'attribute' this will be done in the ldap user entry, if set to 'none' the disable request is not processed. | "attribute" | | `OC_LDAP_GROUP_BASE_DN` | 1.0.0 | string | Search base DN for looking up LDAP groups. | "ou=groups,o=libregraph-idm" | | `OC_LDAP_GROUP_FILTER` | 1.0.0 | string | LDAP filter to add to the default filters for group searches. | "" | -| `OC_LDAP_GROUP_OBJECTCLASS` | 1.0.0 | string | The object class to use for groups in the default group search filter ('groupOfNames'). | "groupOfNames" | +| `OC_LDAP_GROUP_OBJECTCLASS` | 1.0.0 | string | The object class to use for groups in the default group search filter like 'groupOfNames'. | "groupOfNames" | | `OC_LDAP_GROUP_SCHEMA_DISPLAYNAME` | 1.0.0 | string | LDAP Attribute to use for the displayname of groups (often the same as groupname attribute). | "cn" | | `OC_LDAP_GROUP_SCHEMA_GROUPNAME` | 1.0.0 | string | LDAP Attribute to use for the name of groups. | "cn" | -| `OC_LDAP_GROUP_SCHEMA_ID` | 1.0.0 | string | LDAP Attribute to use as the unique id for groups. This should be a stable globally unique id (e.g. a UUID). | "openCloudUUID" | -| `OC_LDAP_GROUP_SCHEMA_ID_IS_OCTETSTRING` | 1.0.0 | bool | Set this to true if the defined 'id' attribute for groups is of the 'OCTETSTRING' syntax. This is e.g. required when using the 'objectGUID' attribute of Active Directory for the group IDs. | "false" | +| `OC_LDAP_GROUP_SCHEMA_ID` | 1.0.0 | string | LDAP Attribute to use as the unique ID for groups. This should be a stable globally unique ID like a UUID. | "openclouduuid" | +| `OC_LDAP_GROUP_SCHEMA_ID_IS_OCTETSTRING` | 1.0.0 | bool | Set this to true if the defined 'id' attribute for groups is of the 'OCTETSTRING' syntax. This is e.g. required when using the 'objectGUID' attribute of Active Directory for the group ID's. | "false" | | `OC_LDAP_GROUP_SCHEMA_MAIL` | 1.0.0 | string | LDAP Attribute to use for the email address of groups (can be empty). | "mail" | | `OC_LDAP_GROUP_SCHEMA_MEMBER` | 1.0.0 | string | LDAP Attribute that is used for group members. | "member" | | `OC_LDAP_GROUP_SCOPE` | 1.0.0 | string | LDAP search scope to use when looking up groups. Supported values are 'base', 'one' and 'sub'. | "sub" | | `OC_LDAP_INSECURE` | 1.0.0 | bool | Disable TLS certificate validation for the LDAP connections. Do not set this in production environments. | "false" | | `OC_LDAP_LOOKUP_CACHE_TTL` | 7.5.0 | Duration | The time to live for the in-memory cache of LDAP lookups. This cache is used to reduce the number of LDAP queries for user and group lookups. | "10s" | | `OC_LDAP_SERVER_WRITE_ENABLED` | 1.0.0 | bool | Allow creating, modifying and deleting LDAP users via the GRAPH API. This can only be set to 'true' when keeping default settings for the LDAP user and group attribute types (the 'OC_LDAP_USER_SCHEMA_* and 'OC_LDAP_GROUP_SCHEMA_* variables). | "true" | -| `OC_LDAP_URI` | 1.0.0 | string | Url of the LDAP service to use as IDP. | "ldap://localhost:9236" | +| `OC_LDAP_URI` | 1.0.0 | string | URI of the LDAP Server to connect to. Supported URI schemes are 'ldaps://' and 'ldap://' | "ldap://localhost:9236" | | `OC_LDAP_USER_BASE_DN` | 1.0.0 | string | Search base DN for looking up LDAP users. | "ou=users,o=libregraph-idm" | -| `OC_LDAP_USER_ENABLED_ATTRIBUTE` | 1.0.0 | string | LDAP Attribute to use as a flag telling if the user is enabled or disabled. | "openCloudUserEnabled" | +| `OC_LDAP_USER_ENABLED_ATTRIBUTE` | 1.0.0 | string | LDAP attribute to use as a flag telling if the user is enabled or disabled. | "openclouduserenabled" | | `OC_LDAP_USER_FILTER` | 1.0.0 | string | LDAP filter to add to the default filters for user search like '(objectclass=openCloudUser)'. | "" | -| `OC_LDAP_USER_OBJECTCLASS` | 1.0.0 | string | LDAP User ObjectClass like 'inetOrgPerson'. | "inetOrgPerson" | +| `OC_LDAP_USER_OBJECTCLASS` | 1.0.0 | string | The object class to use for users in the default user search filter like 'inetOrgPerson'. | "inetOrgPerson" | | `OC_LDAP_USER_SCHEMA_DISPLAYNAME` | 1.0.0 | string | LDAP Attribute to use for the displayname of users. | "displayname" | -| `OC_LDAP_USER_SCHEMA_ID` | 1.0.0 | string | LDAP User UUID attribute like 'uid'. | "openCloudUUID" | -| `OC_LDAP_USER_SCHEMA_ID_IS_OCTETSTRING` | 1.0.0 | bool | Set this to true if the defined 'ID' attribute for users is of the 'OCTETSTRING' syntax. This is e.g. required when using the 'objectGUID' attribute of Active Directory for the user IDs. | "false" | -| `OC_LDAP_USER_SCHEMA_MAIL` | 1.0.0 | string | LDAP User email attribute like 'mail'. | "mail" | +| `OC_LDAP_USER_SCHEMA_ID` | 1.0.0 | string | LDAP Attribute to use as the unique ID for users. This should be a stable globally unique ID like a UUID. | "openclouduuid" | +| `OC_LDAP_USER_SCHEMA_ID_IS_OCTETSTRING` | 1.0.0 | bool | Set this to true if the defined 'ID' attribute for users is of the 'OCTETSTRING' syntax. This is e.g. required when using the 'objectGUID' attribute of Active Directory for the user ID's. | "false" | +| `OC_LDAP_USER_SCHEMA_MAIL` | 1.0.0 | string | LDAP Attribute to use for the email address of users. | "mail" | | `OC_LDAP_USER_SCHEMA_TENANT_ID` | 4.0.0 | string | LDAP Attribute to use for the tenant ID of users. This is used to identify the tenant of a user in a multi-tenant environment. | "" | -| `OC_LDAP_USER_SCHEMA_USERNAME` | 1.0.0 | string | LDAP User name attribute like 'displayName'. | "displayName" | +| `OC_LDAP_USER_SCHEMA_USERNAME` | 1.0.0 | string | LDAP Attribute to use for username of users. | "uid" | | `OC_LDAP_USER_SCHEMA_USER_TYPE` | 1.0.0 | string | LDAP Attribute to distinguish between 'Member' and 'Guest' users. Default is 'openCloudUserType'. | "openCloudUserType" | -| `OC_LDAP_USER_SCOPE` | 1.0.0 | string | LDAP search scope to use when looking up users. Supported scopes are 'base', 'one' and 'sub'. | "sub" | +| `OC_LDAP_USER_SCOPE` | 1.0.0 | string | LDAP search scope to use when looking up users. Supported values are 'base', 'one' and 'sub'. | "sub" | | `OC_LOG_LEVEL` | 1.0.0 | string | The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'. | "error" | -| `OC_MACHINE_AUTH_API_KEY` | 1.0.0 | string | Machine auth API key used to validate internal requests necessary for the access to resources from other services. | "" | -| `OC_MAX_CONCURRENCY` | 1.0.0 | int | Maximum number of concurrent go-routines. Higher values can potentially get work done faster but will also cause more load on the system. Values of 0 or below will be ignored and the default value will be used. | "0" | -| `OC_OIDC_CLIENT_ID` | 1.0.0 | string | The OIDC client ID which OpenCloud Web uses. This client needs to be set up in your IDP. Note that this setting has no effect when using the builtin IDP. | "web" | +| `OC_MACHINE_AUTH_API_KEY` | 1.0.0 | string | The machine auth API key used to validate internal requests necessary to access resources from other services. | "" | +| `OC_MAX_CONCURRENCY` | 1.0.0 | int | The maximum number of concurrent requests the service will handle. | "20" | +| `OC_OIDC_CLIENT_ID` | 6.0.0 | string | The OIDC client ID for Android app. | "OpenCloudAndroid" | | `OC_OIDC_CLIENT_SCOPES` | 6.0.0 | []string | The OIDC client scopes the Android app should request. | "[openid profile email offline_access]" | -| `OC_OIDC_ISSUER` | 1.0.0 | string | The OIDC issuer URL to assign to the demo users. | "https://localhost:9200" | +| `OC_OIDC_ISSUER` | 1.0.0 | string | URL of the OIDC issuer. It defaults to URL of the builtin IDP. | "https://localhost:9200" | | `OC_PASSWORD_POLICY_BANNED_PASSWORDS_LIST` | 1.0.0 | string | Path to the 'banned passwords list' file. This only impacts public link password validation. See the documentation for more details. | "" | | `OC_PASSWORD_POLICY_DISABLED` | 1.0.0 | bool | Disable the password policy. Defaults to false if not set. | "false" | | `OC_PASSWORD_POLICY_MIN_CHARACTERS` | 1.0.0 | int | Define the minimum password length. Defaults to 8 if not set. | "8" | @@ -97,27 +97,27 @@ | `OC_PERSISTENT_STORE_ENABLE_TLS` | 7.3.0 | bool | Enable TLS for the connection to the store. Only applies when store type 'nats-js-kv' is configured. | "false" | | `OC_PERSISTENT_STORE_NODES` | 1.0.0 | []string | A list of nodes to access the configured store. This has no effect when 'memory' store is configured. Note that the behaviour how nodes are used is dependent on the library of the configured store. See the Environment Variable Types description for more details. | "[127.0.0.1:9233]" | | `OC_PERSISTENT_STORE_TLS_INSECURE` | 7.3.0 | bool | Whether to verify the server TLS certificates. | "false" | -| `OC_PERSISTENT_STORE_TLS_ROOT_CA_CERTIFICATE` | 7.3.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided ACTIVITYLOG_STORE_TLS_INSECURE will be seen as false. | "" | -| `OC_PERSISTENT_STORE_TTL` | 1.0.0 | Duration | Time to live for events in the store. See the Environment Variable Types description for more details. | "0s" | -| `OC_REVA_GATEWAY` | 1.0.0 | string | CS3 gateway used to look up user metadata | "eu.opencloud.api.gateway" | +| `OC_PERSISTENT_STORE_TLS_ROOT_CA_CERTIFICATE` | 7.3.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided NOTIFICATIONS_STORE_TLS_INSECURE will be seen as false. | "" | +| `OC_PERSISTENT_STORE_TTL` | 1.0.0 | Duration | Time to live for notifications in the store. Defaults to '336h' (2 weeks). See the Environment Variable Types description for more details. | "336h0m0s" | +| `OC_REVA_GATEWAY` | 1.0.0 | string | The CS3 gateway endpoint. | "eu.opencloud.api.gateway" | | `OC_SERVICE_ACCOUNT_ID` | 1.0.0 | string | The ID of the service account the service should use. See the 'auth-service' service description for more details. | "" | | `OC_SERVICE_ACCOUNT_SECRET` | 1.0.0 | string | The service account secret. | "" | | `OC_SHARING_PUBLIC_SHARE_MUST_HAVE_PASSWORD` | 1.0.0 | bool | Set this to true if you want to enforce passwords on all public shares. | "true" | | `OC_SHARING_PUBLIC_WRITEABLE_SHARE_MUST_HAVE_PASSWORD` | 1.0.0 | bool | Set this to true if you want to enforce passwords for writable shares. Only effective if the setting for 'passwords on all public shares' is set to false. | "false" | | `OC_SHOW_USER_EMAIL_IN_RESULTS` | 1.0.0 | bool | Include user email addresses in responses. If absent or set to false emails will be omitted from results. Please note that admin users can always see all email addresses. | "false" | | `OC_SPACES_MAX_QUOTA` | 1.0.0 | uint64 | Set the global max quota value in bytes. A value of 0 equals unlimited. The value is provided via capabilities. | "0" | -| `OC_SYSTEM_USER_API_KEY` | 1.0.0 | string | API key for the STORAGE-SYSTEM system user. | "" | -| `OC_SYSTEM_USER_ID` | 1.0.0 | string | ID of the OpenCloud STORAGE-SYSTEM system user. Admins need to set the ID for the STORAGE-SYSTEM system user in this config option which is then used to reference the user. Any reasonable long string is possible, preferably this would be an UUIDv4 format. | "" | -| `OC_SYSTEM_USER_IDP` | 1.0.0 | string | IDP of the OpenCloud STORAGE-SYSTEM system user. | "internal" | -| `OC_TRANSFER_SECRET` | 1.0.0 | string | Transfer secret for signing file up- and download requests. | "" | +| `OC_SYSTEM_USER_API_KEY` | 4.0.0 | string | API key for the STORAGE-SYSTEM system user. | "" | +| `OC_SYSTEM_USER_ID` | 4.0.0 | string | ID of the OpenCloud STORAGE-SYSTEM system user. Admins need to set the ID for the STORAGE-SYSTEM system user in this config option which is then used to reference the user. Any reasonable long string is possible, preferably this would be an UUIDv4 format. | "" | +| `OC_SYSTEM_USER_IDP` | 4.0.0 | string | IDP of the OpenCloud STORAGE-SYSTEM system user. | "internal" | +| `OC_TRANSFER_SECRET` | 7.5.0 | string | The storage transfer secret. | "" | | `OC_TRANSLATION_PATH` | 1.0.0 | string | (optional) Set this to a path with custom translations to overwrite the builtin translations. Note that file and folder naming rules apply, see the documentation for more details. | "" | -| `OC_URL` | 1.0.0 | string | The OIDC issuer URL to assign to the demo users. | "https://localhost:9200" | -| `OC_WOPI_DISABLE_CHAT` | 1.0.0 | bool | Disable the chat functionality of the office app. | "false" | +| `OC_URL` | 1.0.0 | string | The public facing URL of the OpenCloud Web UI, used e.g. when sending notification eMails | "https://localhost:9200" | +| `OC_WOPI_DISABLE_CHAT` | 1.0.0 | bool | Disable chat in the office web frontend. This feature applies to OnlyOffice and Microsoft. | "false" | | `SEARCH_EVENTS_ACK_WAIT` | 4.0.0 | Duration | The time to wait for an ack before the message is redelivered. This is used to ensure that messages are not lost if the consumer crashes. | "1m0s" | -| `SEARCH_EVENTS_MAX_ACK_PENDING` | 4.0.0 | int | The maximum number of unacknowledged messages. This is used to limit the number of messages that can be in flight at the same time. | "1000" | -| `STORAGE_GATEWAY_GRPC_ADDR` | 1.0.0 | string | GRPC address of the STORAGE-SYSTEM service. | "eu.opencloud.api.storage-system" | -| `STORAGE_GRPC_ADDR` | 1.0.0 | string | GRPC address of the STORAGE-SYSTEM service. | "eu.opencloud.api.storage-system" | +| `SEARCH_EVENTS_MAX_ACK_PENDING` | 4.0.0 | int | The maximum number of unacknowledged messages. This is used to limit the number of messages that can be in flight at the same time. | "10000" | +| `STORAGE_GATEWAY_GRPC_ADDR` | 4.0.0 | string | GRPC address of the STORAGE-SYSTEM service. | "eu.opencloud.api.storage-system" | +| `STORAGE_GRPC_ADDR` | 4.0.0 | string | GRPC address of the STORAGE-SYSTEM service. | "eu.opencloud.api.storage-system" | | `STORAGE_USERS_ASYNC_PROPAGATOR_PROPAGATION_DELAY` | 1.0.0 | Duration | The delay between a change made to a tree and the propagation start on treesize and treetime. Multiple propagations are computed to a single one. See the Environment Variable Types description for more details. | "0s" | | `STORAGE_USERS_PERMISSION_ENDPOINT` | 1.0.0 | string | Endpoint of the permissions service. The endpoints can differ for 'decomposed' and 'decomposeds3'. | "eu.opencloud.api.settings" | -| `WEB_OIDC_CLIENT_ID` | 1.0.0 | string | The OIDC client ID which OpenCloud Web uses. This client needs to be set up in your IDP. Note that this setting has no effect when using the builtin IDP. | "web" | -| `WEB_OIDC_SCOPE` | 1.0.0 | string | OIDC scopes to request during authentication to authorize access to user details. Defaults to 'openid profile email'. Values are separated by blank. More example values but not limited to are 'address' or 'phone' etc. | "openid profile email" | +| `WEB_OIDC_CLIENT_ID` | 6.0.0 | string | The OIDC client ID for the OpenCloud web client. The 'WEB_OIDC_CLIENT_ID' setting is only here for backwards compatibility and will be removed in a future release. | "web" | +| `WEB_OIDC_SCOPE` | 6.0.0 | []string | The OIDC client scopes the OpenCloud web client should request. The 'WEB_OIDC_SCOPE' setting is only here for backwards compatibility and will be removed in a future release. | "[openid profile email]" | diff --git a/docs/_static/env-vars/graph.yaml b/docs/_static/env-vars/graph.yaml index 30487c31..4b758d14 100644 --- a/docs/_static/env-vars/graph.yaml +++ b/docs/_static/env-vars/graph.yaml @@ -21,6 +21,7 @@ debug: pprof: false zpages: false http: + disabled: false addr: 127.0.0.1:9120 root: /graph tls: @@ -48,6 +49,8 @@ http: - Purge - Restore allow_credentials: true + metrics: + disabled: true api: group_members_patch_limit: 20 graph_username_match: default @@ -119,8 +122,13 @@ identity: school_number_attribute: "" school_id_attribute: "" school_termination_min_grace_days: 0 + metrics: + disabled: true + metrics: + disabled: true include_ocm_sharees: false events: + disabled_consumer: false endpoint: 127.0.0.1:9233 cluster: opencloud-cluster tls_insecure: false diff --git a/docs/_static/env-vars/graph_configvars.md b/docs/_static/env-vars/graph_configvars.md index 88af6f09..475f3e52 100644 --- a/docs/_static/env-vars/graph_configvars.md +++ b/docs/_static/env-vars/graph_configvars.md @@ -18,6 +18,7 @@ |`GRAPH_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|`""`| |`GRAPH_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`"false"`| |`GRAPH_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`"false"`| +|`GRAPH_HTTP_DISABLE`| %NEXT% |bool|`Disables the HTTP service. Set this to true if the service should only consume events.`|`"false"`| |`GRAPH_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`"127.0.0.1:9120"`| |`GRAPH_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`"/graph"`| |`OC_HTTP_TLS_ENABLED`| 1.0.0 |bool|`Activates TLS for the http based services using the server certifcate and key configured via OC_HTTP_TLS_CERTIFICATE and OC_HTTP_TLS_KEY. If OC_HTTP_TLS_CERTIFICATE is not set a temporary server certificate is generated - to be used with PROXY_INSECURE_BACKEND=true.`|`"false"`| @@ -28,6 +29,7 @@ |`OC_CORS_ALLOW_METHODS`
`GRAPH_CORS_ALLOW_METHODS`| 1.0.0 |[]string|`A list of allowed CORS methods. See following chapter for more details: *Access-Control-Request-Method* at \https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method. See the Environment Variable Types description for more details.`|`"[GET POST PUT PATCH DELETE OPTIONS]"`| |`OC_CORS_ALLOW_HEADERS`
`GRAPH_CORS_ALLOW_HEADERS`| 1.0.0 |[]string|`A list of allowed CORS headers. See following chapter for more details: *Access-Control-Request-Headers* at \https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Headers. See the Environment Variable Types description for more details.`|`"[Authorization Origin Content-Type Accept X-Requested-With X-Request-Id Purge Restore]"`| |`OC_CORS_ALLOW_CREDENTIALS`
`GRAPH_CORS_ALLOW_CREDENTIALS`| 1.0.0 |bool|`Allow credentials for CORS.See following chapter for more details: *Access-Control-Allow-Credentials* at \https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials.`|`"true"`| +|`GRAPH_HTTP_METRICS_DISABLE`| %NEXT% |bool|`Disables the metrics for the HTTP service.`|`"true"`| |`GRAPH_GROUP_MEMBERS_PATCH_LIMIT`| 1.0.0 |int|`The amount of group members allowed to be added with a single patch request.`|`"20"`| |`GRAPH_USERNAME_MATCH`| 1.0.0 |string|`Apply restrictions to usernames. Supported values are 'default' and 'none'. When set to 'default', user names must not start with a number and are restricted to ASCII characters. When set to 'none', no restrictions are applied. The default value is 'default'.`|`"default"`| |`GRAPH_ASSIGN_DEFAULT_USER_ROLE`| 1.0.0 |bool|`Whether to assign newly created users the default role 'User'. Set this to 'false' if you want to assign roles manually, or if the role assignment should happen at first login. Set this to 'true' (the default) to assign the role 'User' when creating a new user.`|`"true"`| @@ -89,7 +91,10 @@ |`GRAPH_LDAP_SCHOOL_NUMBER_ATTRIBUTE`| 1.0.0 |string|`LDAP Attribute to use for the number of a school.`|`""`| |`GRAPH_LDAP_SCHOOL_ID_ATTRIBUTE`| 1.0.0 |string|`LDAP Attribute to use as the unique id for schools. This should be a stable globally unique ID like a UUID.`|`""`| |`GRAPH_LDAP_SCHOOL_TERMINATION_MIN_GRACE_DAYS`| 1.0.0 |int|`When setting a 'terminationDate' for a school, require the date to be at least this number of days in the future.`|`"0"`| +|`GRAPH_LDAP_METRICS_DISABLE`| %NEXT% |bool|`Disables the metrics for outbound LDAP operations.`|`"true"`| +|`GRAPH_IDENTITY_BACKEND_METRICS_DISABLE`| %NEXT% |bool|`Disables the metrics for inbound identity backend operations.`|`"true"`| |`OC_ENABLE_OCM`
`GRAPH_INCLUDE_OCM_SHAREES`| 1.0.0 |bool|`Include OCM sharees when listing users.`|`"false"`| +|`GRAPH_EVENTS_DISABLE_CONSUMER`| %NEXT% |bool|`Disables consuming events. Set this to true if the service should only handle HTTP requests.`|`"false"`| |`OC_EVENTS_ENDPOINT`
`GRAPH_EVENTS_ENDPOINT`| 1.0.0 |string|`The address of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture. Set to a empty string to disable emitting events.`|`"127.0.0.1:9233"`| |`OC_EVENTS_CLUSTER`
`GRAPH_EVENTS_CLUSTER`| 1.0.0 |string|`The clusterID of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture.`|`"opencloud-cluster"`| |`OC_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`GRAPH_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`"false"`| diff --git a/docs/_static/env-vars/graph_readme.md b/docs/_static/env-vars/graph_readme.md index 9b48eb18..02315562 100755 --- a/docs/_static/env-vars/graph_readme.md +++ b/docs/_static/env-vars/graph_readme.md @@ -24,6 +24,12 @@ for a detailed specification of the API implemented by the graph service. * [Translation Rules](#translation-rules) * [Default Language](#default-language) * [Unified Role Management](#unified-role-management) +* [API Handlers](#api-handlers) +* [Metrics](#metrics) + * [Graph User Password Change Counter Metric](#graph-user-password-change-counter-metric) + * [Graph Inbound HTTP Request Duration Metrics](#graph-inbound-http-request-duration-metrics) + * [Graph Outbound LDAP Operation Duration Metrics](#graph-outbound-ldap-operation-duration-metrics) + * [Graph Identity Backend API Duration Metrics](#graph-identity-backend-api-duration-metrics) ## Sequence Diagram @@ -188,7 +194,7 @@ The output of this command includes the following information for each role: * `Condition` * `Allowed resource actions` -**Example output (shortned)** +**Example output (shortened)** ```bash +--------------------------------------+----------+--------------------------------+--------------------------------+------------------------------------------+ @@ -204,4 +210,96 @@ The output of this command includes the following information for each role: +--------------------------------------+----------+--------------------------------+--------------------------------+------------------------------------------+ ``` +## API Handlers + +To specialize `graph` service instances in order to scale them independently, it is possible to disable its API handlers: + +* `GRAPH_HTTP_DISABLE`: when set to `true`, the service does not listen on HTTP and only consumes events (defaults to `false`) +* `GRAPH_EVENTS_DISABLE_CONSUMER`: when set to `true`, the service does not consome events and only listens on HTTP (defaults to `false`) + +## Metrics + +Metrics are disabled by default, and must be enabled using the following environment variables: + +* `GRAPH_LDAP_METRICS_DISABLE`: set to `false` to enable metrics for the duration of outbound LDAP client operations (defaults to `true`) +* `GRAPH_HTTP_METRICS_DISABLE`: set to `false` to enable metrics for the duration of inbound Graph HTTP API requests (defaults to `true`) +* `GRAPH_IDENTITY_BACKEND_METRICS_DISABLE`: set to `false` to enable metrics for the duration of Graph identity backend operations (defaults to `true`) + +The `graph` service provides the following metrics: + +| Name | Description | +| ---- | ----------- | +| `opencloud_graph_build_info{version=...}` | Contains a label `version` that is set to the current version of the service, and always has a value of `1` | +| `opencloud_graph_events_enabled` | Is set to `1` if the Events API handler is enabled, or `0` if not | +| `opencloud_graph_http_enabled` | Is set to `1` if the HTTP API handler is enabled, or `0` if not | +| `opencloud_graph_events{event=...,result=...}` | Counts the number of events that have been consumed, with a `event` label that contains the name of the event, and a `result` label that is set to `success` or `failure` | +| `opencloud_graph_events_invalid` | Counts the number of invalid events that are malformed or are missing required data | +| `opencloud_graph_events_unsupported` | Counts the numbef of consumed events that cannot be processes by this service, should always be `0` | +| `opencloud_graph_user_password_changes{result=...,reason=...}` | Counts the number of user password change attempts, including the reason for failure when `result`=`failure` | +| `opencloud_graph_http_request_duration_seconds{method=...,path=...,version=...,resource=...,code=...,result=...}` | Histogram that measures the duration of Graph HTTP API requests, in buckets | +| `opencloud_graph_http_requests` | Gauge that counts the number of concurrent inbound HTTP requests to the Graph API | +| `opencloud_graph_ldap_client_operation_duration_seconds{uri=...,write=...,operation=...,result=...}` | Histogram that measures the duration of outbound LDAP operations | +| `opencloud_graph_ldap_client_operations{uri=...,write=...}` | Gauge that counts the number of concurrent outbound LDAP operations | +| `opencloud_graph_identity_backend_api_duration_seconds{type=...,operation=...,result=...}` | Histogram that measures the duration of requests to the Graph identity backend, in buckets | + +To create some moderate load on a running `opencloud` instance, one can use the k6 script `load_test.js` as follows: + +```bash +k6 run --vus=10 --duration=3m ./load_test.js +``` + +The following environment variables can be used to influence its behavior: + + * `BASE_URL`: defaults to `https://localhost:9200` + * `USERNAME`: defaults to `alan` + * `PASSWORD`: defaults to `demo` + +For example, to use a different user and a different URL: + +```bash +k6 run --vus=10 --duration=3m -e USERNAME=lynn -e BASE_URL=https://localhost:9201 ./load_test.js +``` + +It is not meant to be a feature test suite, but merely a small k6 script to generate some read-only load in order to make Grafana displays. + +### Graph User Password Change Counter Metric + +For `opencloud_graph_user_password_changes`: + +* `result` is either + * `success`: when the password was changed successfully + * `failure`: when the password could not be changed, the reason being tracked in the `reason` label +* `reason` is either + * empty when `result` is `success` + * `invalid`: when parameters were invalid, such as the new password being an empty password + * `error`: when an error prevented the password change, such as a network failure + * `wrong-password`: when the password change was refused because the current password is wrong + +### Graph Inbound HTTP Request Duration Metrics + +For `opencloud_graph_http_request_duration_seconds`: + +* `method` is the HTTP method (`GET`, `PUT`, ...) +* `path` is the canonical request path with placeholders (e.g. `/v1beta1/drives/{driveID}/root/children`) +* `version` is the Graph API version (`v1beta` or `v1.0`) +* `resource` is the top-level resource after the version (`me`, `application`, `drives`, ...) +* `code` is the resulting HTTP status code (`200`, `404`, `500`, ...) +* `result` is one of `success`, `client-error`, `server-error` + +### Graph Outbound LDAP Operation Duration Metrics + +For `opencloud_graph_ldap_client_operation_duration_seconds`: + +* `operation` is the name of the LDAP operation (`add`, `delete`, `modify`, `modify-dn`, ...) +* `result` is either `success`, `failure`, `read-only` (when attempting a write operation on a LDAP server that is configured as read-only in OpenCloud) or `not-found` +* `uri` contains the LDAP server URI the client is connected to +* `write` is set to `1` if the LDAP client is allowed to perform write operations, or to `0` if it is configured to be read-only + +### Graph Identity Backend API Duration Metrics + +* `type` is the type of the identity backend that is being used (`ldap` or `cs3`) +* `operation` is the name of the API operation (`create-user`, `get-users`, ...) +* `result` is `success`, `failure` or `not-found` + + diff --git a/docs/_static/env-vars/storage-users_configvars.md b/docs/_static/env-vars/storage-users_configvars.md index 561d57e4..2583c967 100644 --- a/docs/_static/env-vars/storage-users_configvars.md +++ b/docs/_static/env-vars/storage-users_configvars.md @@ -1,5 +1,5 @@ -2026-09-01-12-00-11 +2026-09-04-00-08-14 ## Deprecation Notice diff --git a/docs/_static/env-vars/web_configvars.md b/docs/_static/env-vars/web_configvars.md index 024f3ebf..8710c3db 100644 --- a/docs/_static/env-vars/web_configvars.md +++ b/docs/_static/env-vars/web_configvars.md @@ -1,5 +1,5 @@ -2026-09-01-12-00-11 +2026-09-04-00-08-14 ## Deprecation Notice