diff --git a/docs/_static/env-vars/frontend_configvars.md b/docs/_static/env-vars/frontend_configvars.md index e46f9952..f897e221 100644 --- a/docs/_static/env-vars/frontend_configvars.md +++ b/docs/_static/env-vars/frontend_configvars.md @@ -1,5 +1,5 @@ -2026-08-10-00-05-27 +2026-08-13-00-06-08 ## Deprecation Notice diff --git a/docs/_static/env-vars/global_configvars.md b/docs/_static/env-vars/global_configvars.md index b729ef19..a8e7b959 100644 --- a/docs/_static/env-vars/global_configvars.md +++ b/docs/_static/env-vars/global_configvars.md @@ -2,7 +2,7 @@ | Name | Introduction Version | Type | Description | Default Value | |---|---|---|---|---| -| `IDM_CREATE_DEMO_USERS` | 1.0.0 | bool | The default role assignments the demo users should be setup. | "false" | +| `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 | Password for the configured store. Only applies when store type 'nats-js-kv' is configured. | "" | @@ -20,16 +20,16 @@ | `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_EVENTS_AUTH_PASSWORD` | 1.0.0 | string | Password for the events broker. | "" | -| `OC_EVENTS_AUTH_USERNAME` | 1.0.0 | string | Username for the events broker. | "" | +| `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" | | `OC_EVENTS_ENABLE_TLS` | 1.0.0 | bool | Enable TLS for the connection to the events broker. The events broker is the OpenCloud service which receives and delivers events between the services. | "false" | | `OC_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. | "127.0.0.1:9233" | -| `OC_EVENTS_TLS_INSECURE` | 1.0.0 | bool | Whether to verify the server TLS certificates. | "false" | -| `OC_EVENTS_TLS_ROOT_CA_CERTIFICATE` | 1.0.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided SHARING_EVENTS_TLS_INSECURE will be seen as false. | "" | +| `OC_EVENTS_TLS_INSECURE` | 1.0.0 | bool | Whether the OpenCloud server should skip the client certificate verification during the TLS handshake. | "false" | +| `OC_EVENTS_TLS_ROOT_CA_CERTIFICATE` | 1.0.0 | string | The root CA certificate used to validate the server's TLS certificate. If provided POSTPROCESSING_EVENTS_TLS_INSECURE will be seen as false. | "" | | `OC_GATEWAY_GRPC_ADDR` | 1.0.0 | string | The bind address of the GRPC service. | "127.0.0.1:9142" | | `OC_GRPC_CLIENT_TLS_CACERT` | 1.0.0 | string | Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the go-micro based grpc services. | "" | | `OC_GRPC_CLIENT_TLS_MODE` | 1.0.0 | string | TLS mode for grpc connection to the go-micro based grpc services. Possible values are 'off', 'insecure' and 'on'. 'off': disables transport security for the clients. 'insecure' allows using transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates). 'on' enables transport security, including server certificate verification. | "" | @@ -37,7 +37,7 @@ | `OC_HTTP_TLS_CERTIFICATE` | 1.0.0 | string | Path/File name of the TLS server certificate (in PEM format) for the http services. | "" | | `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" | | `OC_HTTP_TLS_KEY` | 1.0.0 | string | Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services. | "" | -| `OC_INSECURE` | 1.0.0 | bool | Whether to verify the server TLS certificates. | "false" | +| `OC_INSECURE` | 7.3.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. | "" | @@ -45,9 +45,9 @@ | `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=reva,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=idp,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/idm. | "" | +| `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_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" | @@ -55,32 +55,32 @@ | `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_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_GROUP_SCOPE` | 1.0.0 | string | LDAP search scope to use when looking up groups. Supported scopes 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_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 | URI of the LDAP Server to connect to. Supported URI schemes are 'ldaps://' and 'ldap://' | "ldap://localhost:9236" | +| `OC_LDAP_URI` | 1.0.0 | string | Url of the LDAP service to use as IDP. | "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 | The object class to use for users in the default user search filter ('inetOrgPerson'). | "inetOrgPerson" | +| `OC_LDAP_USER_OBJECTCLASS` | 1.0.0 | string | LDAP User ObjectClass 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 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 IDs. | "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_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 ID's. | "false" | +| `OC_LDAP_USER_SCHEMA_MAIL` | 1.0.0 | string | LDAP User email attribute like 'mail'. | "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 Attribute to use for username of users. | "uid" | +| `OC_LDAP_USER_SCHEMA_USERNAME` | 1.0.0 | string | LDAP User name attribute like 'displayName'. | "displayName" | | `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 values are 'base', 'one' and 'sub'. | "sub" | +| `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_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 | The machine auth API key used to validate internal requests necessary to access 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. | "1" | | `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_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 identity provider value to set in the userids of the CS3 user objects for users returned by this user provider. | "https://localhost:9200" | +| `OC_OIDC_ISSUER` | 1.0.0 | string | The OIDC issuer URL to use. | "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" | @@ -88,14 +88,14 @@ | `OC_PASSWORD_POLICY_MIN_LOWERCASE_CHARACTERS` | 1.0.0 | int | Define the minimum number of uppercase letters. Defaults to 1 if not set. | "1" | | `OC_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_MIN_UPPERCASE_CHARACTERS` | 1.0.0 | int | Define the minimum number of lowercase letters. Defaults to 1 if not set. | "1" | -| `OC_PERSISTENT_STORE` | 1.0.0 | string | The type of the store. Supported values are: 'memory', 'nats-js-kv', 'redis-sentinel', 'noop'. See the text description for details. | "nats-js-kv" | +| `OC_PERSISTENT_STORE` | 1.0.0 | string | The type of the store. Supported values are: 'memory', 'redis-sentinel', 'nats-js-kv', 'noop'. See the text description for details. | "nats-js-kv" | | `OC_PERSISTENT_STORE_AUTH_PASSWORD` | 1.0.0 | string | The password to authenticate with the store. Only applies when store type 'nats-js-kv' is configured. | "" | | `OC_PERSISTENT_STORE_AUTH_USERNAME` | 1.0.0 | string | The username to authenticate with the store. Only applies when store type 'nats-js-kv' is configured. | "" | | `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 EVENTHISTORY_STORE_TLS_INSECURE will be seen as false. | "" | -| `OC_PERSISTENT_STORE_TTL` | 1.0.0 | Duration | Time to live for events in the store. Defaults to '336h' (2 weeks). See the Environment Variable Types description for more details. | "0s" | +| `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 POSTPROCESSING_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. | "168h0m0s" | | `OC_REVA_GATEWAY` | 1.0.0 | string | The CS3 gateway endpoint. | "eu.opencloud.api.gateway" | | `OC_SERVICE_ACCOUNT_ID` | 7.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` | 7.0.0 | string | The service account secret. | "" | @@ -108,7 +108,7 @@ | `OC_SYSTEM_USER_IDP` | 1.0.0 | string | IDP of the OpenCloud STORAGE-SYSTEM system user. | "internal" | | `OC_TRANSFER_SECRET` | 1.0.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 identity provider value to set in the userids of the CS3 user objects for users returned by this user provider. | "https://localhost:9200" | +| `OC_URL` | 1.0.0 | string | The OIDC issuer URL to use. | "https://localhost:9200" | | `OC_WOPI_DISABLE_CHAT` | 1.0.0 | bool | Disable the chat functionality of the office app. | "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. | "10000" | diff --git a/docs/_static/env-vars/policies_readme.md b/docs/_static/env-vars/policies_readme.md index 65da0438..64c15789 100755 --- a/docs/_static/env-vars/policies_readme.md +++ b/docs/_static/env-vars/policies_readme.md @@ -3,9 +3,11 @@ ## Abstract -The policies service provides a new gRPC API which can be used to check whether a requested operation is allowed or not. To do so, Open Policy Agent (OPA) is used to define the set of rules of what is permitted and what is not. +The policies service provides a new gRPC API which can be used to check whether a requested operation is allowed or not. +To do so, Open Policy Agent (OPA) is used to define the set of rules of what is permitted and what is not. -Policies are written in the [rego query language](https://www.openpolicyagent.org/docs/latest/policy-language/). The location of the rego files can be configured via yaml, a configuration via environment variables is not possible. +Policies are written in the [rego query language](https://www.openpolicyagent.org/docs/latest/policy-language/). The +location of the rego files can be configured via yaml, a configuration via environment variables is not possible. ## Table of Contents @@ -20,6 +22,7 @@ Policies are written in the [rego query language](https://www.openpolicyagent.or * [Proxy](#proxy) * [Postprocessing](#postprocessing) * [Rego Key Match](#rego-key-match) +* [Rego Extensions](#rego-extensions) * [Extend Mimetype File Extension Mapping](#extend-mimetype-file-extension-mapping) * [Example Policies](#example-policies) @@ -27,27 +30,30 @@ Policies are written in the [rego query language](https://www.openpolicyagent.or The policies service consists of the following modules: -* Proxy authorization (middleware) -* Event authorization (async post-processing) -* gRPC API (can be used by other services) +* Proxy authorization (middleware) +* Event authorization (async post-processing) +* gRPC API (can be used by other services) To configure the policies service, three environment variables need to be defined: -* `POLICIES_ENGINE_TIMEOUT` -* `POLICIES_POSTPROCESSING_QUERY` -* `PROXY_POLICIES_QUERY` +* `POLICIES_ENGINE_TIMEOUT` +* `POLICIES_POSTPROCESSING_QUERY` +* `PROXY_POLICIES_QUERY` -Note that each query setting defines the [Complete Rules](https://www.openpolicyagent.org/docs/latest/#complete-rules) variable defined in the rego rule set the corresponding step uses for the evaluation. If the variable is mistyped or not found, the evaluation defaults to deny. Individual query definitions can be defined for each module. +Note that each query setting defines the [Complete Rules](https://www.openpolicyagent.org/docs/latest/#complete-rules) +variable defined in the rego rule set the corresponding step uses for the evaluation. If the variable is mistyped or not +found, the evaluation defaults to deny. Individual query definitions can be defined for each module. -To activate the policies service for a module, it must be started with a yaml configuration that points to one or more rego files. Note that if the service is scaled horizontally, each instance should have access to the same rego files to avoid unpredictable results. If a file path has been configured but the file is not present or accessible, the evaluation defaults to deny. +To activate the policies service for a module, it must be started with a yaml configuration that points to at least one +rego file that contains the complete rule variable to be queried. Note that if the service is scaled horizontally, each +instance should have access to the same rego files to avoid unpredictable results. -When using async post-processing which is done via the postprocessing service, the value `policies` must be added to the `POSTPROCESSING_STEPS` configuration in postprocessing service in the order where the evaluation should take place. +The rego files are read once when the service starts. A changed rule set takes effect after a restart, and a configured +file that is missing or does not parse keeps the service from starting. -variable defined in the Rego rule set the corresponding step uses for the evaluation. If the variable is mistyped or not found, the evaluation defaults to deny. Individual query definitions can be defined for each module. - -To activate the policies service for a module, it must be started with a yaml configuration that points to at least one Rego file that contains the complete rule variable to be queried. Note that if the service is scaled horizontally, each instance should have access to the same Rego files to avoid unpredictable results. If a file path has been configured but the file it is not present or accessible, the evaluation defaults to deny. - -When using async post-processing via the postprocessing service, the value `policies` must be added to the `POSTPROCESSING_STEPS` configuration in the order in which the evaluation should take place. Example: First check if a file contains questionable content via policies. If it looks okay, continue to check for viruses. +When using async post-processing via the postprocessing service, the value `policies` must be added to the +`POSTPROCESSING_STEPS` configuration in the order in which the evaluation should take place. Example: First check if a +file contains questionable content via policies. If it looks okay, continue to check for viruses. For configuration examples, the [Example Policies](#example-policies) from below are used. @@ -55,39 +61,59 @@ For configuration examples, the [Example Policies](#example-policies) from below ### gRPC API -The gRPC API can be used by any other internal service. It can also be used for example by third parties to find out if an action is allowed or not. This layer is already used by the proxy middleware. There is no configuration necessary, because the query setting (complete rule variable) must be part of the request. +The gRPC API can be used by any other internal service. It can also be used for example by third parties to find out if +an action is allowed or not. This layer is already used by the proxy middleware. There is no configuration necessary, +because the query setting (complete rule variable) must be part of the request. ### Proxy Middleware -The proxy service already includes a middleware which uses the internal [gRPC API](#grpc-api) to evaluate the policies. Since the proxy is in heavy use and every HTTP request is processed here, only simple and quick decisions should be evaluated. More complex queries such as file content evaluation are _strongly_ discouraged. +The proxy service already includes a middleware which uses the internal [gRPC API](#grpc-api) to evaluate the policies. +Since the proxy is in heavy use and every HTTP request is processed here, only simple and quick decisions should be +evaluated. More complex queries such as file content evaluation are _strongly_ discouraged. + +The middleware only denies on the outcome of the policy, it makes no decision of its own. Where the file name is not +part of the request path, for example when a single shared resource is uploaded to by its id, the middleware stats the +resource to obtain it. If that stat fails, `input.resource.name` reaches the policy empty and the policy decides what +that means. Prefer policies that state which files are allowed over policies that list what is forbidden, a rule +matching on a specific extension does not match an empty name: + +```rego +granted = false if { + input.resource.name == "" +} +``` -If the evaluation in the proxy results in a "denied" outcome, the response will return a `403 Permission Denied` with the following response body +If the evaluation in the proxy results in a "denied" outcome, the response will return a `403 Permission Denied` with +the following response body ```json { - "error": - { - "code": "deniedByPolicy", - "message": "Operation denied due to security policies", - "innererror": - { - "date": "2023-09-19T13:22:20Z", - "filename": "File", - "method": "POST", - "path": "/dav/spaces/some-space-id/Folder/", - "request-id": "9CFCE925-F9D9-4F26-AB3B-2C1C40A9CD0C" - } + "error": { + "code": "deniedByPolicy", + "message": "Operation denied due to security policies", + "innererror": { + "date": "2023-09-19T13:22:20Z", + "filename": "File", + "method": "POST", + "path": "/dav/spaces/some-space-id/Folder/", + "request-id": "9CFCE925-F9D9-4F26-AB3B-2C1C40A9CD0C" } + } } ``` ### Event Service (Postprocessing) -This layer is event-based and part of the postprocessing service. Since processing at this point is asynchronous, the operations can also take longer and be more expensive, like evaluating the contents of a file. +This layer is event-based and part of the postprocessing service. Since processing at this point is asynchronous, the +operations can also take longer and be more expensive, like evaluating the contents of a file. ## Defining Policies to Evaluate -Each module can have as many policy files as needed for evaluation. Files can also include other files if necessary. To use policies, they have to be saved to a location that is accessible to the policies service. As a good starting point, take the config directory and use a subdirectory collecting all the `.rego` files, though any other directory can be defined. The config directory is already accessible by all services and usually is included in a xref:maintenance/b-r/backup.adoc[backup] plan. +Each module can have as many policy files as needed for evaluation. Files can also include other files if necessary. To +use policies, they have to be saved to a location that is accessible to the policies service. As a good starting point, +take the config directory and use a subdirectory collecting all the `.rego` files, though any other directory can be +defined. The config directory is already accessible by all services and usually is included in a xref: +maintenance/b-r/backup.adoc[backup] plan. If this is done, it's required to configure the policies service to use these files: @@ -102,7 +128,8 @@ policies: - your_path_to_policies/util.rego ``` -Once the references to policy files are configured correctly, the `_QUERY` configuration needs to be defined for the proxy middleware and for the events service. +Once the references to policy files are configured correctly, the `_QUERY` configuration needs to be defined for the +proxy middleware and for the events service. ## Setting the Query Configuration @@ -111,9 +138,11 @@ To define a value for the query evaluation, the following scheme is necessary: `data..` * The keyword `data` is mandatory and must be present. -* The `package-name` is defined in one .rego file like `package postprocessing`. It is not related to the filename. For more details, see the [packages](https://www.openpolicyagent.org/docs/latest/policy-language/#packages) documentation. +* The `package-name` is defined in one .rego file like `package postprocessing`. It is not related to the filename. For + more details, see the [packages](https://www.openpolicyagent.org/docs/latest/policy-language/#packages) documentation. * The `complete-rule-variable-name` is the variable providing the result of the evaluation. -* Exact one of the defined files, which is responsible for returning the evaluation result, must contain the combination of `` and ``. +* Exact one of the defined files, which is responsible for returning the evaluation result, must contain the combination + of `` and ``. ### Proxy @@ -145,29 +174,54 @@ The same can be achieved by setting the following environment variable: export POLICIES_POSTPROCESSING_QUERY=data.postprocessing.granted ``` -As soon as that query is configured, the postprocessing service must be informed to use the policies step by setting the environment variable: +As soon as that query is configured, the postprocessing service must be informed to use the policies step by setting the +environment variable: ```shell export POSTPROCESSING_STEPS=policies ``` -Note that additional steps can be configured and their position in the list defines the order of processing. For details see the postprocessing service documentation. +Note that additional steps can be configured and their position in the list defines the order of processing. For details +see the postprocessing service documentation. ## Rego Key Match -To identify available keys for OPA, you need to look at [engine.go](https://github.com/opencloud-eu/opencloud/blob/main/services/policies/pkg/engine/engine.go) and the [policies.swagger.json](https://github.com/opencloud-eu/opencloud/blob/master/protogen/gen/opencloud/services/policies/v0/policies.swagger.json) file. Note that which keys are available depends on from which module it is used. +To identify available keys for OPA, you need to look +at [engine.go](https://github.com/opencloud-eu/opencloud/blob/main/services/policies/pkg/engine/engine.go) and +the [policies.swagger.json](https://github.com/opencloud-eu/opencloud/blob/master/protogen/gen/opencloud/services/policies/v0/policies.swagger.json) +file. Note that which keys are available depends on from which module it is used. + +## Rego Extensions + +Besides the standard rego built-in functions, the following functions are added on top: + +| Function | Result | Description | +|----------------------------------------------------|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `opencloud.mimetype.extensions("application/pdf")` | `[".pdf"]` | Lists the file extensions associated with a mimetype. See [Extend Mimetype File Extension Mapping](#extend-mimetype-file-extension-mapping). | +| `opencloud.mimetype.detect(bytes)` | `"application/pdf"` | Detects a mimetype from content. The list of known mimetypes is limited. | +| `opencloud.resource.download(input.resource.url)` | bytes | Downloads a resource. Available in the event service (postprocessing) where `input.resource.url` is set. | + +Rego has no byte type, so `opencloud.resource.download` hands the content to the policy as base64. +`opencloud.mimetype.detect` takes that value as it is, a policy working on the content itself has to run it through +`base64.decode` first. + +Note that `opencloud.resource.download` performs an HTTP request and holds the whole resource in memory. Use it in +postprocessing policies only, not in policies evaluated by the proxy middleware. ## Extend Mimetype File Extension Mapping -In the extended set of the rego query language, it is possible to get a list of associated file extensions based on a mimetype, for example `opencloud.mimetype.extensions("application/pdf")`. +In the extended set of the rego query language, it is possible to get a list of associated file extensions based on a +mimetype, for example `opencloud.mimetype.extensions("application/pdf")`. The list of mappings is restricted by default and is provided by the host system OpenCloud is installed on. -In order to extend this list, OpenCloud must be provided with the path to a custom `mime.types` file that maps mimetypes to extensions. -The location for the file must be accessible by all instances of the policy service. As a rule of thumb, use the directory where the OpenCloud configuration files are stored. -Note that existing mappings from the host are extended by the definitions from the mime types file, but not replaced. +In order to extend this list, OpenCloud must be provided with the path to a custom `mime.types` file that maps mimetypes +to extensions. The location for the file must be accessible by all instances of the policy service. As a rule of thumb, +use the directory where the OpenCloud configuration files are stored. Note that existing mappings from the host are +extended by the definitions from the mime types file, but not replaced. -The path to that file can be provided via a yaml configuration or an environment variable. Note to replace the `OC_CONFIG_DIR` string by an existing path. +The path to that file can be provided via a yaml configuration or an environment variable. Note to replace the +`OC_CONFIG_DIR` string by an existing path. ```shell export POLICIES_ENGINE_MIMES=OC_CONFIG_DIR/mime.types @@ -179,9 +233,13 @@ policies: mimes: OC_CONFIG_DIR/mime.types ``` -A good example of how such a file should be formatted can be found in the [Apache svn repository](https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types). +A good example of how such a file should be formatted can be found in +the [Apache svn repository](https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types). ## Example Policies -The policies service contains a set of preconfigured example policies. See the [devtools policie](https://github.com/opencloud-eu/opencloud/tree/main/devtools/deployments/service_policies/policies/) directory for details. The contained policies disallow OpenCloud to create certain file types, both via the proxy middleware and the events service via postprocessing. +The policies service contains a set of preconfigured example policies. See +the [devtools policie](https://github.com/opencloud-eu/opencloud/tree/main/devtools/deployments/service_policies/policies/) +directory for details. The contained policies disallow OpenCloud to create certain file types, both via the proxy +middleware and the events service via postprocessing. diff --git a/docs/_static/env-vars/storage-users_configvars.md b/docs/_static/env-vars/storage-users_configvars.md index bba44d03..00d57f44 100644 --- a/docs/_static/env-vars/storage-users_configvars.md +++ b/docs/_static/env-vars/storage-users_configvars.md @@ -1,5 +1,5 @@ -2026-08-10-00-05-27 +2026-08-13-00-06-08 ## Deprecation Notice @@ -39,9 +39,9 @@ |`STORAGE_USERS_DECOMPOSED_ROOT`| 1.0.0 |string|`The directory where the filesystem storage will store blobs and metadata. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage/users.`|`"/var/lib/opencloud/storage/users"`| |`STORAGE_USERS_DECOMPOSED_USER_LAYOUT`| 1.0.0 |string|`Template string for the user storage layout in the user directory.`|`"{{.Id.OpaqueId}}"`| |`STORAGE_USERS_PERMISSION_ENDPOINT`
`STORAGE_USERS_DECOMPOSED_PERMISSIONS_ENDPOINT`| 1.0.0 |string|`Endpoint of the permissions service. The endpoints can differ for 'decomposed' and 'decomposeds3'.`|`"eu.opencloud.api.settings"`| -|`STORAGE_USERS_DECOMPOSED_PERSONAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct personal space aliases.`|`"{{.SpaceType}}/{{.User.Username \| lower}}"`| +|`STORAGE_USERS_DECOMPOSED_PERSONAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct personal space aliases.`|`"{{.SpaceType}}/{{.User.Username \\| lower}}"`| |`STORAGE_USERS_DECOMPOSED_PERSONAL_SPACE_PATH_TEMPLATE`| 1.0.0 |string|`Template string to construct the paths of the personal space roots.`|`""`| -|`STORAGE_USERS_DECOMPOSED_GENERAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct general space aliases.`|`"{{.SpaceType}}/{{.SpaceName \| replace \" \" \"-\" \| lower}}"`| +|`STORAGE_USERS_DECOMPOSED_GENERAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct general space aliases.`|`"{{.SpaceType}}/{{.SpaceName \\| replace \" \" \"-\" \\| lower}}"`| |`STORAGE_USERS_DECOMPOSED_GENERAL_SPACE_PATH_TEMPLATE`| 1.0.0 |string|`Template string to construct the paths of the projects space roots.`|`""`| |`STORAGE_USERS_DECOMPOSED_SHARE_FOLDER`| 1.0.0 |string|`Name of the folder jailing all shares.`|`"/Shares"`| |`STORAGE_USERS_DECOMPOSED_MAX_ACQUIRE_LOCK_CYCLES`| 1.0.0 |int|`When trying to lock files, OpenCloud will try this amount of times to acquire the lock before failing. After each try it will wait for an increasing amount of time. Values of 0 or below will be ignored and the default value will be used.`|`"20"`| @@ -66,9 +66,9 @@ |`STORAGE_USERS_DECOMPOSEDS3_PUT_OBJECT_CONCURRENT_STREAM_PARTS`| 1.0.0 |bool|`Always precreate parts when copying objects to S3. This is not recommended. It uses a memory buffer. If true, PartSize needs to be set.`|`"false"`| |`STORAGE_USERS_DECOMPOSEDS3_PUT_OBJECT_NUM_THREADS`| 1.0.0 |uint|`Number of concurrent uploads to use when copying objects to S3.`|`"4"`| |`STORAGE_USERS_DECOMPOSEDS3_PUT_OBJECT_PART_SIZE`| 1.0.0 |uint64|`Part size for concurrent uploads to S3. If no value or 0 is set, the library automatically calculates the part size according to the total size of the file to be uploaded. The value range is min 5MB and max 5GB.`|`"0"`| -|`STORAGE_USERS_DECOMPOSEDS3_PERSONAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct personal space aliases.`|`"{{.SpaceType}}/{{.User.Username \| lower}}"`| +|`STORAGE_USERS_DECOMPOSEDS3_PERSONAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct personal space aliases.`|`"{{.SpaceType}}/{{.User.Username \\| lower}}"`| |`STORAGE_USERS_DECOMPOSEDS3_PERSONAL_SPACE_PATH_TEMPLATE`| 1.0.0 |string|`Template string to construct the paths of the personal space roots.`|`""`| -|`STORAGE_USERS_DECOMPOSEDS3_GENERAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct general space aliases.`|`"{{.SpaceType}}/{{.SpaceName \| replace \" \" \"-\" \| lower}}"`| +|`STORAGE_USERS_DECOMPOSEDS3_GENERAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct general space aliases.`|`"{{.SpaceType}}/{{.SpaceName \\| replace \" \" \"-\" \\| lower}}"`| |`STORAGE_USERS_DECOMPOSEDS3_GENERAL_SPACE_PATH_TEMPLATE`| 1.0.0 |string|`Template string to construct the paths of the projects space roots.`|`""`| |`STORAGE_USERS_DECOMPOSEDS3_SHARE_FOLDER`| 1.0.0 |string|`Name of the folder jailing all shares.`|`"/Shares"`| |`STORAGE_USERS_DECOMPOSEDS3_MAX_ACQUIRE_LOCK_CYCLES`| 1.0.0 |int|`When trying to lock files, OpenCloud will try this amount of times to acquire the lock before failing. After each try it will wait for an increasing amount of time. Values of 0 or below will be ignored and the default value of 20 will be used.`|`"20"`| @@ -89,9 +89,9 @@ |`STORAGE_USERS_POSIX_ROOT`| 1.0.0 |string|`The directory where the filesystem storage will store its data. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage/users.`|`"/var/lib/opencloud/storage/users"`| |`OC_DECOMPOSEDFS_PROPAGATOR`
`STORAGE_USERS_POSIX_PROPAGATOR`| 2.0.0 |string|`The propagator used for the posix driver. At the moment, only 'sync' is fully supported, 'async' is available as an experimental option.`|`""`| |`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_POSIX_PERSONAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct personal space aliases.`|`"{{.SpaceType}}/{{.User.Username \| lower}}"`| +|`STORAGE_USERS_POSIX_PERSONAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct personal space aliases.`|`"{{.SpaceType}}/{{.User.Username \\| lower}}"`| |`STORAGE_USERS_POSIX_PERSONAL_SPACE_PATH_TEMPLATE`| 1.0.0 |string|`Template string to construct the paths of the personal space roots.`|`"users/{{.User.Id.OpaqueId}}"`| -|`STORAGE_USERS_POSIX_GENERAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct general space aliases.`|`"{{.SpaceType}}/{{.SpaceName \| replace \" \" \"-\" \| lower}}"`| +|`STORAGE_USERS_POSIX_GENERAL_SPACE_ALIAS_TEMPLATE`| 1.0.0 |string|`Template string to construct general space aliases.`|`"{{.SpaceType}}/{{.SpaceName \\| replace \" \" \"-\" \\| lower}}"`| |`STORAGE_USERS_POSIX_GENERAL_SPACE_PATH_TEMPLATE`| 1.0.0 |string|`Template string to construct the paths of the projects space roots.`|`"projects/{{.SpaceId}}"`| |`STORAGE_USERS_PERMISSION_ENDPOINT`
`STORAGE_USERS_POSIX_PERMISSIONS_ENDPOINT`| 1.0.0 |string|`Endpoint of the permissions service. The endpoints can differ for 'decomposed', 'posix' and 'decomposeds3'.`|`"eu.opencloud.api.settings"`| |`OC_ASYNC_UPLOADS`| 1.0.0 |bool|`Enable asynchronous file uploads.`|`"true"`| diff --git a/docs/_static/env-vars/web_configvars.md b/docs/_static/env-vars/web_configvars.md index ed1a97dc..9090424e 100644 --- a/docs/_static/env-vars/web_configvars.md +++ b/docs/_static/env-vars/web_configvars.md @@ -1,5 +1,5 @@ -2026-08-10-00-05-27 +2026-08-13-00-06-08 ## Deprecation Notice