From 11a50581317f52a00681c9c95a55aa4af5482ab0 Mon Sep 17 00:00:00 2001 From: openclouders Date: Thu, 15 Jan 2026 10:35:01 +0000 Subject: [PATCH] Update docs with latest env vars --- .../dev/_static/env-vars/activitylog.yaml | 58 +++ .../env-vars/activitylog_configvars.mdx | 40 ++ .../env-vars/activitylog_deprecation.mdx | 0 .../_static/env-vars/activitylog_readme.mdx | 64 +++ .../dev/_static/env-vars/antivirus.yaml | 31 ++ .../_static/env-vars/antivirus_configvars.mdx | 27 + .../env-vars/antivirus_deprecation.mdx | 0 .../dev/_static/env-vars/antivirus_readme.mdx | 109 ++++ .../dev/_static/env-vars/app-provider.yaml | 36 ++ .../env-vars/app-provider_configvars.mdx | 30 ++ .../env-vars/app-provider_deprecation.mdx | 0 .../_static/env-vars/app-provider_readme.mdx | 41 ++ .../dev/_static/env-vars/app-registry.yaml | 106 ++++ .../env-vars/app-registry_configvars.mdx | 15 + .../env-vars/app-registry_deprecation.mdx | 0 .../_static/env-vars/app-registry_readme.mdx | 473 +++++++++++++++++ .../dev/_static/env-vars/audit.yaml | 22 + .../dev/_static/env-vars/audit_configvars.mdx | 20 + .../_static/env-vars/audit_deprecation.mdx | 0 .../dev/_static/env-vars/audit_readme.mdx | 48 ++ .../dev/_static/env-vars/auth-app.yaml | 60 +++ .../_static/env-vars/auth-app_configvars.mdx | 35 ++ .../_static/env-vars/auth-app_deprecation.mdx | 0 .../dev/_static/env-vars/auth-app_readme.mdx | 164 ++++++ .../dev/_static/env-vars/auth-basic.yaml | 67 +++ .../env-vars/auth-basic_configvars.mdx | 56 ++ .../env-vars/auth-basic_deprecation.mdx | 0 .../_static/env-vars/auth-basic_readme.mdx | 56 ++ .../dev/_static/env-vars/auth-bearer.yaml | 27 + .../env-vars/auth-bearer_configvars.mdx | 21 + .../env-vars/auth-bearer_deprecation.mdx | 0 .../_static/env-vars/auth-bearer_readme.mdx | 43 ++ .../dev/_static/env-vars/auth-machine.yaml | 22 + .../env-vars/auth-machine_configvars.mdx | 17 + .../env-vars/auth-machine_deprecation.mdx | 0 .../_static/env-vars/auth-machine_readme.mdx | 38 ++ .../dev/_static/env-vars/auth-service.yaml | 23 + .../env-vars/auth-service_configvars.mdx | 17 + .../env-vars/auth-service_deprecation.mdx | 0 .../_static/env-vars/auth-service_readme.mdx | 41 ++ .../dev/_static/env-vars/clientlog.yaml | 24 + .../_static/env-vars/clientlog_configvars.mdx | 20 + .../env-vars/clientlog_deprecation.mdx | 0 .../dev/_static/env-vars/clientlog_readme.mdx | 34 ++ .../dev/_static/env-vars/collaboration.yaml | 54 ++ .../env-vars/collaboration_configvars.mdx | 42 ++ .../env-vars/collaboration_deprecation.mdx | 0 .../_static/env-vars/collaboration_readme.mdx | 91 ++++ .../dev/_static/env-vars/eventhistory.yaml | 30 ++ .../env-vars/eventhistory_configvars.mdx | 24 + .../env-vars/eventhistory_deprecation.mdx | 0 .../_static/env-vars/eventhistory_readme.mdx | 56 ++ .../_static/env-vars/extended_configvars.mdx | 336 ++++++++++++ .../dev/_static/env-vars/frontend.yaml | 166 ++++++ .../_static/env-vars/frontend_configvars.mdx | 124 +++++ .../_static/env-vars/frontend_deprecation.mdx | 4 + .../dev/_static/env-vars/frontend_readme.mdx | 176 +++++++ .../dev/_static/env-vars/gateway.yaml | 63 +++ .../_static/env-vars/gateway_configvars.mdx | 54 ++ .../_static/env-vars/gateway_deprecation.mdx | 0 .../dev/_static/env-vars/gateway_readme.mdx | 196 +++++++ .../_static/env-vars/global_configvars.mdx | 110 ++++ .../dev/_static/env-vars/graph.yaml | 160 ++++++ .../dev/_static/env-vars/graph_configvars.mdx | 116 +++++ .../_static/env-vars/graph_deprecation.mdx | 0 .../dev/_static/env-vars/graph_readme.mdx | 217 ++++++++ .../dev/_static/env-vars/groups.yaml | 63 +++ .../_static/env-vars/groups_configvars.mdx | 53 ++ .../_static/env-vars/groups_deprecation.mdx | 0 .../dev/_static/env-vars/groups_readme.mdx | 51 ++ .../dev/_static/env-vars/idm.yaml | 22 + .../dev/_static/env-vars/idm_configvars.mdx | 20 + .../dev/_static/env-vars/idm_deprecation.mdx | 0 .../dev/_static/env-vars/idm_readme.mdx | 27 + .../dev/_static/env-vars/idp.yaml | 113 +++++ .../dev/_static/env-vars/idp_configvars.mdx | 55 ++ .../dev/_static/env-vars/idp_deprecation.mdx | 0 .../dev/_static/env-vars/idp_readme.mdx | 102 ++++ .../dev/_static/env-vars/invitations.yaml | 31 ++ .../env-vars/invitations_configvars.mdx | 25 + .../env-vars/invitations_deprecation.mdx | 0 .../_static/env-vars/invitations_readme.mdx | 68 +++ .../dev/_static/env-vars/nats.yaml | 18 + .../dev/_static/env-vars/nats_configvars.mdx | 17 + .../dev/_static/env-vars/nats_deprecation.mdx | 0 .../dev/_static/env-vars/nats_readme.mdx | 47 ++ .../dev/_static/env-vars/notifications.yaml | 48 ++ .../env-vars/notifications_configvars.mdx | 40 ++ .../env-vars/notifications_deprecation.mdx | 0 .../_static/env-vars/notifications_readme.mdx | 130 +++++ .../dev/_static/env-vars/ocm.yaml | 109 ++++ .../dev/_static/env-vars/ocm_configvars.mdx | 53 ++ .../dev/_static/env-vars/ocm_deprecation.mdx | 0 .../dev/_static/env-vars/ocm_readme.mdx | 154 ++++++ .../dev/_static/env-vars/ocs.yaml | 45 ++ .../dev/_static/env-vars/ocs_configvars.mdx | 24 + .../dev/_static/env-vars/ocs_deprecation.mdx | 0 .../dev/_static/env-vars/ocs_readme.mdx | 44 ++ .../dev/_static/env-vars/policies.yaml | 27 + .../_static/env-vars/policies_configvars.mdx | 20 + .../_static/env-vars/policies_deprecation.mdx | 0 .../dev/_static/env-vars/policies_readme.mdx | 197 ++++++++ .../dev/_static/env-vars/postprocessing.yaml | 34 ++ .../env-vars/postprocessing_configvars.mdx | 30 ++ .../env-vars/postprocessing_deprecation.mdx | 0 .../env-vars/postprocessing_readme.mdx | 166 ++++++ .../dev/_static/env-vars/proxy.yaml | 240 +++++++++ .../dev/_static/env-vars/proxy_configvars.mdx | 68 +++ .../_static/env-vars/proxy_deprecation.mdx | 0 .../dev/_static/env-vars/proxy_readme.mdx | 358 +++++++++++++ .../dev/_static/env-vars/search.yaml | 69 +++ .../_static/env-vars/search_configvars.mdx | 54 ++ .../_static/env-vars/search_deprecation.mdx | 0 .../dev/_static/env-vars/search_readme.mdx | 159 ++++++ .../dev/_static/env-vars/settings.yaml | 64 +++ .../_static/env-vars/settings_configvars.mdx | 40 ++ .../_static/env-vars/settings_deprecation.mdx | 0 .../dev/_static/env-vars/settings_readme.mdx | 478 ++++++++++++++++++ .../dev/_static/env-vars/sharing.yaml | 76 +++ .../_static/env-vars/sharing_configvars.mdx | 60 +++ .../_static/env-vars/sharing_deprecation.mdx | 0 .../dev/_static/env-vars/sharing_readme.mdx | 65 +++ .../dev/_static/env-vars/sse.yaml | 41 ++ .../dev/_static/env-vars/sse_configvars.mdx | 27 + .../dev/_static/env-vars/sse_deprecation.mdx | 0 .../dev/_static/env-vars/sse_readme.mdx | 40 ++ .../_static/env-vars/storage-publiclink.yaml | 23 + .../storage-publiclink_configvars.mdx | 17 + .../storage-publiclink_deprecation.mdx | 0 .../env-vars/storage-publiclink_readme.mdx | 60 +++ .../dev/_static/env-vars/storage-shares.yaml | 24 + .../env-vars/storage-shares_configvars.mdx | 19 + .../env-vars/storage-shares_deprecation.mdx | 0 .../env-vars/storage-shares_readme.mdx | 56 ++ .../dev/_static/env-vars/storage-system.yaml | 42 ++ .../env-vars/storage-system_configvars.mdx | 32 ++ .../env-vars/storage-system_deprecation.mdx | 0 .../env-vars/storage-system_readme.mdx | 41 ++ .../dev/_static/env-vars/storage-users.yaml | 195 +++++++ .../env-vars/storage-users_configvars.mdx | 147 ++++++ .../env-vars/storage-users_deprecation.mdx | 4 + .../_static/env-vars/storage-users_readme.mdx | 256 ++++++++++ .../dev/_static/env-vars/thumbnails.yaml | 63 +++ .../env-vars/thumbnails_configvars.mdx | 31 ++ .../env-vars/thumbnails_deprecation.mdx | 0 .../_static/env-vars/thumbnails_readme.mdx | 152 ++++++ .../dev/_static/env-vars/userlog.yaml | 58 +++ .../_static/env-vars/userlog_configvars.mdx | 41 ++ .../_static/env-vars/userlog_deprecation.mdx | 0 .../dev/_static/env-vars/userlog_readme.mdx | 115 +++++ .../dev/_static/env-vars/users.yaml | 68 +++ .../dev/_static/env-vars/users_configvars.mdx | 58 +++ .../_static/env-vars/users_deprecation.mdx | 0 .../dev/_static/env-vars/users_readme.mdx | 50 ++ .../dev/_static/env-vars/web.yaml | 122 +++++ .../dev/_static/env-vars/web_configvars.mdx | 52 ++ .../dev/_static/env-vars/web_deprecation.mdx | 0 .../dev/_static/env-vars/web_readme.mdx | 206 ++++++++ .../dev/_static/env-vars/webdav.yaml | 40 ++ .../_static/env-vars/webdav_configvars.mdx | 22 + .../_static/env-vars/webdav_deprecation.mdx | 0 .../dev/_static/env-vars/webdav_readme.mdx | 45 ++ .../dev/_static/env-vars/webfinger.yaml | 35 ++ .../_static/env-vars/webfinger_configvars.mdx | 22 + .../env-vars/webfinger_deprecation.mdx | 0 .../dev/_static/env-vars/webfinger_readme.mdx | 144 ++++++ 166 files changed, 9816 insertions(+) create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/extended_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/global_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_readme.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger.yaml create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_configvars.mdx create mode 100644 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_deprecation.mdx create mode 100755 versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_readme.mdx diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog.yaml new file mode 100644 index 00000000..4227cda1 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog.yaml @@ -0,0 +1,58 @@ +# Autogenerated +# Filename: activitylog.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9197 + token: "" + pprof: false + zpages: false +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" +store: + store: nats-js-kv + nodes: + - 127.0.0.1:9233 + database: activitylog + table: "" + ttl: 0s + username: "" + password: "" +reva_gateway: eu.opencloud.api.gateway +grpc_client_tls: null +http: + addr: 127.0.0.1:9195 + root: / + cors: + allow_origins: + - '*' + allow_methods: + - GET + allow_headers: + - Authorization + - Origin + - Content-Type + - Accept + - X-Requested-With + - X-Request-Id + - Ocs-Apirequest + allow_credentials: true + tls: + enabled: false + cert: "" + key: "" +token_manager: + jwt_secret: "" +translation_path: "" +default_language: en +service_account: + service_account_id: "" + service_account_secret: "" +write_buffer_duration: 10s +max_activities: 6000 diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_configvars.mdx new file mode 100644 index 00000000..c4ea3285 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_configvars.mdx @@ -0,0 +1,40 @@ +Environment variables for the **activitylog** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`ACTIVITYLOG_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`ACTIVITYLOG_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9197`| +|`ACTIVITYLOG_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`ACTIVITYLOG_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`ACTIVITYLOG_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`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_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_INSECURE`
`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 NOTIFICATIONS_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`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_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_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_PERSISTENT_STORE`
`ACTIVITYLOG_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_NODES`
`ACTIVITYLOG_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]`| +|`ACTIVITYLOG_STORE_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`activitylog`| +|`ACTIVITYLOG_STORE_TABLE`| 1.0.0 |string|`The database table the store should use.`|``| +|`OC_PERSISTENT_STORE_TTL`
`ACTIVITYLOG_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_PERSISTENT_STORE_AUTH_USERNAME`
`ACTIVITYLOG_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_AUTH_PASSWORD`
`ACTIVITYLOG_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_REVA_GATEWAY`| 1.0.0 |string|`CS3 gateway used to look up user metadata`|`eu.opencloud.api.gateway`| +|`ACTIVITYLOG_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9195`| +|`ACTIVITYLOG_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/`| +|`OC_CORS_ALLOW_ORIGINS`
`ACTIVITYLOG_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_CORS_ALLOW_METHODS`
`ACTIVITYLOG_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_HEADERS`
`ACTIVITYLOG_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_CREDENTIALS`
`ACTIVITYLOG_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_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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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_JWT_SECRET`
`ACTIVITYLOG_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_TRANSLATION_PATH`
`ACTIVITYLOG_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_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_SERVICE_ACCOUNT_ID`
`ACTIVITYLOG_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`
`ACTIVITYLOG_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| +|`ACTIVITYLOG_WRITE_BUFFER_DURATION`| 4.0.0 |Duration|`The duration to wait before flushing the write buffer. This is used to reduce the number of writes to the store.`|`10s`| +|`ACTIVITYLOG_MAX_ACTIVITIES`| 4.0.0 |int|`The maximum number of activities to keep in the store per resource. If the number of activities exceeds this value, the oldest activities will be removed.`|`6000`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_readme.mdx new file mode 100755 index 00000000..ecea2ca6 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/activitylog_readme.mdx @@ -0,0 +1,64 @@ +--- +title: Activitylog +date: 2026-01-15T10:35:01.38855066Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/activitylog +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `activitylog` service is responsible for storing events (activities) per resource. + + +## Table of Contents + +* [The Log Service Ecosystem](#the-log-service-ecosystem) +* [Activitylog Store](#activitylog-store) +* [Translations](#translations) + * [Translation Rules](#translation-rules) +* [Default Language](#default-language) + +## The Log Service Ecosystem + +Log services like the `activitylog`, `userlog`, `clientlog` and `sse` are responsible for composing notifications for a specific audience. + - The `userlog` service translates and adjusts messages to be human readable. + - The `clientlog` service composes machine readable messages, so clients can act without the need to query the server. + - The `sse` service is only responsible for sending these messages. It does not care about their form or language. + - The `activitylog` service stores events per resource. These can be retrieved to show item activities + +## Activitylog Store + +The `activitylog` stores activities for each resource. It works in conjunction with the `eventhistory` service to keep the data it needs to store to a minimum. + +## Translations + +The `activitylog` service has embedded translations sourced via transifex to provide a basic set of translated languages. These embedded translations are available for all deployment scenarios. In addition, the service supports custom translations, though it is currently not possible to just add custom translations to embedded ones. If custom translations are configured, the embedded ones are not used. To configure custom translations, the `ACTIVITYLOG_TRANSLATION_PATH` environment variable needs to point to a base folder that will contain the translation files. This path must be available from all instances of the activitylog service, a shared storage is recommended. Translation files must be of type [.po](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html#PO-Files) or [.mo](https://www.gnu.org/software/gettext/manual/html_node/Binaries.html). For each language, the filename needs to be `activitylog.po` (or `activitylog.mo`) and stored in a folder structure defining the language code. In general the path/name pattern for a translation file needs to be: + +```text +{ACTIVITYLOG_TRANSLATION_PATH}/{language-code}/LC_MESSAGES/activitylog.po +``` + +The language code pattern is composed of `language[_territory]` where `language` is the base language and `_territory` is optional and defines a country. + +For example, for the language `de`, one needs to place the corresponding translation files to `{ACTIVITYLOG_TRANSLATION_PATH}/de_DE/LC_MESSAGES/activitylog.po`. + + + +Important: For the time being, the embedded OpenCloud Web frontend only supports the main language code but does not handle any territory. When strings are available in the language code `language_territory`, the web frontend does not see it as it only requests `language`. In consequence, any translations made must exist in the requested `language` to avoid a fallback to the default. + +### Translation Rules + +* If a requested language code is not available, the service tries to fall back to the base language if available. For example, if the requested language-code `de_DE` is not available, the service tries to fall back to translations in the `de` folder. +* If the base language `de` is also not available, the service falls back to the system's default English (`en`), +which is the source of the texts provided by the code. + +## Default Language + +The default language can be defined via the `OC_DEFAULT_LANGUAGE` environment variable. See the `settings` service for a detailed description. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus.yaml new file mode 100644 index 00000000..28b354ee --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus.yaml @@ -0,0 +1,31 @@ +# Autogenerated +# Filename: antivirus.yaml + +file: "" +loglevel: error +debug: + addr: 127.0.0.1:9277 + token: "" + pprof: false + zpages: false +infected-file-handling: delete +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" +workers: 10 +scanner: + type: clamav + clamav: + socket: /run/clamav/clamd.ctl + scan_timeout: 5m0s + icap: + scan_timeout: 5m0s + url: icap://127.0.0.1:1344 + service: avscan +max-scan-size: 100MB +max-scan-size-mode: partial diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_configvars.mdx new file mode 100644 index 00000000..e46a295d --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_configvars.mdx @@ -0,0 +1,27 @@ +Environment variables for the **antivirus** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`ANTIVIRUS_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`ANTIVIRUS_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9277`| +|`ANTIVIRUS_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`ANTIVIRUS_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`ANTIVIRUS_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`ANTIVIRUS_INFECTED_FILE_HANDLING`| 1.0.0 |string|`Defines the behaviour when a virus has been found. Supported options are: 'delete', 'continue' and 'abort '. Delete will delete the file. Continue will mark the file as infected but continues further processing. Abort will keep the file in the uploads folder for further admin inspection and will not move it to its final destination.`|`delete`| +|`OC_EVENTS_ENDPOINT`
`ANTIVIRUS_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_CLUSTER`
`ANTIVIRUS_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`ANTIVIRUS_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`ANTIVIRUS_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided ANTIVIRUS_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`ANTIVIRUS_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_AUTH_USERNAME`
`ANTIVIRUS_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_AUTH_PASSWORD`
`ANTIVIRUS_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.`|``| +|`ANTIVIRUS_WORKERS`| 1.0.0 |int|`The number of concurrent go routines that fetch events from the event queue.`|`10`| +|`ANTIVIRUS_SCANNER_TYPE`| 1.0.0 |ScannerType|`The antivirus scanner to use. Supported values are 'clamav' and 'icap'.`|`clamav`| +|`ANTIVIRUS_CLAMAV_SOCKET`| 1.0.0 |string|`The socket clamav is running on. Note the default value is an example which needs adaption according your OS.`|`/run/clamav/clamd.ctl`| +|`ANTIVIRUS_CLAMAV_SCAN_TIMEOUT`| 2.1.0 |Duration|`Scan timeout for the ClamAV client. Defaults to '5m' (5 minutes). See the Environment Variable Types description for more details.`|`5m0s`| +|`ANTIVIRUS_ICAP_SCAN_TIMEOUT`| 1.0.0 |Duration|`Scan timeout for the ICAP client. Defaults to '5m' (5 minutes). See the Environment Variable Types description for more details.`|`5m0s`| +|`ANTIVIRUS_ICAP_URL`| 1.0.0 |string|`URL of the ICAP server.`|`icap://127.0.0.1:1344`| +|`ANTIVIRUS_ICAP_SERVICE`| 1.0.0 |string|`The name of the ICAP service.`|`avscan`| +|`ANTIVIRUS_MAX_SCAN_SIZE`| 1.0.0 |string|`The maximum scan size the virus scanner can handle.0 means unlimited. Usable common abbreviations: [KB, KiB, MB, MiB, GB, GiB, TB, TiB, PB, PiB, EB, EiB], example: 2GB.`|`100MB`| +|`ANTIVIRUS_MAX_SCAN_SIZE_MODE`| 2.1.0 |MaxScanSizeMode|`Defines the mode of handling files that exceed the maximum scan size. Supported options are: 'skip', which skips files that are bigger than the max scan size, and 'truncate' (default), which only uses the file up to the max size.`|`partial`| +|`ANTIVIRUS_DEBUG_SCAN_OUTCOME`| 1.0.0 |string|`A predefined outcome for virus scanning, FOR DEBUG PURPOSES ONLY! (example values: 'found,infected')`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_readme.mdx new file mode 100755 index 00000000..80fb1953 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/antivirus_readme.mdx @@ -0,0 +1,109 @@ +--- +title: Antivirus +date: 2026-01-15T10:35:01.388829869Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/antivirus +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `antivirus` service is responsible for scanning files for viruses. + + +## Table of Contents + +* [Memory Considerations](#memory-considerations) +* [Configuration](#configuration) + * [Antivirus Scanner Type](#antivirus-scanner-type) + * [Maximum Scan Size](#maximum-scan-size) + * [Antivirus Workers](#antivirus-workers) + * [Infected File Handling](#infected-file-handling) + * [Scanner Inaccessibility](#scanner-inaccessibility) +* [Operation Modes](#operation-modes) + * [Postprocessing](#postprocessing) + * [Scaling in Kubernetes](#scaling-in-kubernetes) + +## Memory Considerations + +The antivirus service can consume considerable amounts of memory. +This is relevant to provide or define sufficient memory for the deployment selected. +To avoid out of memory (OOM) situations, the following equation gives a rough overview based on experiences made. +The memory calculation comes without any guarantee, is intended as overview only and subject of change. + +`memory limit` = `max file size` x `workers` x `factor 8 - 14` + +With: +`ANTIVIRUS_WORKERS` == 1 +```plaintext + 50MB file --> factor 14 --> 700MB memory +844MB file --> factor 8,3 --> 7GB memory +``` + +## Configuration + +### Antivirus Scanner Type + +The antivirus service currently supports [ICAP](https://tools.ietf.org/html/rfc3507) and [ClamAV](http://www.clamav.net/index.html) as antivirus scanners. +The `ANTIVIRUS_SCANNER_TYPE` environment variable is used to select the scanner. +The detailed configuration for each scanner heavily depends on the scanner type selected. +See the environment variables for more details. + + - For `icap`, only scanners using the `X-Infection-Found` header are currently supported. + - For `clamav` only local sockets can currently be configured. + +### Maximum Scan Size + +Several factors can make it necessary to limit the maximum filesize the antivirus service uses for scanning. +Use the `ANTIVIRUS_MAX_SCAN_SIZE` environment variable to scan only a given number of bytes, +or to skip the whole resource. + +Even if it is recommended to scan the whole file, several factors like scanner type and version, +bandwidth, performance issues, etc. might make a limit necessary. + +In such cases, the antivirus max scan size mode can be handy, the following modes are available: + + - `partial`: The file is scanned up to the given size. The rest of the file is not scanned. This is the default mode `ANTIVIRUS_MAX_SCAN_SIZE_MODE=partial` + - `skip`: The file is skipped and not scanned. `ANTIVIRUS_MAX_SCAN_SIZE_MODE=skip` + +**IMPORTANT** +> Streaming of files to the virus scan service still [needs to be implemented](https://github.com/owncloud/ocis/issues/6803). +> To prevent OOM errors `ANTIVIRUS_MAX_SCAN_SIZE` needs to be set lower than available ram and or the maximum file size that can be scanned by the virus scanner. + +### Antivirus Workers + +The number of concurrent scans can be increased by setting `ANTIVIRUS_WORKERS`. Be aware that this will also increase memory usage. + +### Infected File Handling + +The antivirus service allows three different ways of handling infected files. Those can be set via the `ANTIVIRUS_INFECTED_FILE_HANDLING` environment variable: + + - `delete`: (default): Infected files will be deleted immediately, further postprocessing is cancelled. + - `abort`: (advanced option): Infected files will be kept, further postprocessing is cancelled. Files can be manually retrieved and inspected by an admin. To identify the file for further investigation, the antivirus service logs the abort/infected state including the file ID. The file is located in the `storage/users/uploads` folder of the OpenCloud data directory and persists until it is manually deleted by the admin via the [Manage Unfinished Uploads](https://github.com/opencloud-eu/opencloud/tree/main/services/storage-users#manage-unfinished-uploads) command. + - `continue`: (not recommended): Infected files will be marked via metadata as infected, but postprocessing continues normally. Note: Infected Files are moved to their final destination and therefore not prevented from download, which includes the risk of spreading viruses. + +In all cases, a log entry is added declaring the infection and handling method and a notification via the `userlog` service sent. + +### Scanner Inaccessibility + +In case a scanner is not accessible by the antivirus service like a network outage, service outage or hardware outage, the antivirus service uses the `abort` case for further processing, independent of the actual setting made. In any case, an error is logged noting the inaccessibility of the scanner used. + +## Operation Modes + +The antivirus service can scan files during `postprocessing`. `on demand` scanning is currently not available and might be added in a future release. + +### Postprocessing + +The antivirus service will scan files during postprocessing. It listens for a postprocessing step called `virusscan`. This step can be added in the environment variable `POSTPROCESSING_STEPS`. Read the documentation of the [postprocessing service](https://github.com/opencloud-eu/opencloud/tree/main/services/postprocessing) for more details. + +The number of concurrent scans can be increased by setting `ANTIVIRUS_WORKERS`, but be aware that this will also increase the memory usage. + +### Scaling in Kubernetes + +In kubernetes, `ANTIVIRUS_WORKERS` and `ANTIVIRUS_MAX_SCAN_SIZE` can be used to trigger the horizontal pod autoscaler by requesting a memory size that is below `ANTIVIRUS_MAX_SCAN_SIZE`. Keep in mind that `ANTIVIRUS_MAX_SCAN_SIZE` amount of memory might be held by `ANTIVIRUS_WORKERS` number of go routines. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider.yaml new file mode 100644 index 00000000..917bf3ac --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider.yaml @@ -0,0 +1,36 @@ +# Autogenerated +# Filename: app-provider.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9165 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9164 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +external_addr: eu.opencloud.api.app-provider +driver: "" +drivers: + wopi: + app_api_key: "" + app_desktop_only: false + app_icon_uri: "" + app_internal_url: "" + app_name: "" + app_url: "" + app_disable_chat: false + insecure: false + wopi_server_iop_secret: "" + wopi_server_external_url: "" + wopi_folder_url_base_url: https://localhost:9200/ + wopi_folder_url_path_template: /f/{{.ResourceID}} diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_configvars.mdx new file mode 100644 index 00000000..67310fd8 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_configvars.mdx @@ -0,0 +1,30 @@ +Environment variables for the **app-provider** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`APP_PROVIDER_SERVICE_NAME`| 1.0.0 |string|`The name of the service. This needs to be changed when using more than one app provider. Each app provider configured needs to be identified by a unique service name. Possible examples are: 'app-provider-collabora', 'app-provider-onlyoffice', 'app-provider-office365'.`|`app-provider`| +|`OC_LOG_LEVEL`
`APP_PROVIDER_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`APP_PROVIDER_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9165`| +|`APP_PROVIDER_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint`|``| +|`APP_PROVIDER_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling`|`false`| +|`APP_PROVIDER_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing traces in-memory.`|`false`| +|`APP_PROVIDER_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9164`| +|`OC_GRPC_PROTOCOL`
`APP_PROVIDER_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GPRC service.`|`tcp`| +|`OC_JWT_SECRET`
`APP_PROVIDER_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`APP_PROVIDER_EXTERNAL_ADDR`| 1.0.0 |string|`Address of the app provider, where the GATEWAY service can reach it.`|`eu.opencloud.api.app-provider`| +|`APP_PROVIDER_DRIVER`| 1.0.0 |string|`Driver, the APP PROVIDER services uses. Only 'wopi' is supported as of now.`|``| +|`APP_PROVIDER_WOPI_APP_API_KEY`| 1.0.0 |string|`API key for the wopi app.`|``| +|`APP_PROVIDER_WOPI_APP_DESKTOP_ONLY`| 1.0.0 |bool|`Offer this app only on desktop.`|`false`| +|`APP_PROVIDER_WOPI_APP_ICON_URI`| 1.0.0 |string|`URI to an app icon to be used by clients.`|``| +|`APP_PROVIDER_WOPI_APP_INTERNAL_URL`| 1.0.0 |string|`Internal URL to the app, like in your DMZ.`|``| +|`APP_PROVIDER_WOPI_APP_NAME`| 1.0.0 |string|`Human readable app name.`|``| +|`APP_PROVIDER_WOPI_APP_URL`| 1.0.0 |string|`URL for end users to access the app.`|``| +|`APP_PROVIDER_WOPI_DISABLE_CHAT`
`OC_WOPI_DISABLE_CHAT`| 1.0.0 |bool|`Disable the chat functionality of the office app.`|`false`| +|`APP_PROVIDER_WOPI_INSECURE`| 1.0.0 |bool|`Disable TLS certificate validation for requests to the WOPI server and the web office application. Do not set this in production environments.`|`false`| +|`APP_PROVIDER_WOPI_WOPI_SERVER_IOP_SECRET`| 1.0.0 |string|`Shared secret of the CS3org WOPI server.`|``| +|`APP_PROVIDER_WOPI_WOPI_SERVER_EXTERNAL_URL`| 1.0.0 |string|`External url of the CS3org WOPI server.`|``| +|`OC_URL`
`APP_PROVIDER_WOPI_FOLDER_URL_BASE_URL`| 1.0.0 |string|`Base url to navigate back from the app to the containing folder in the file list.`|`https://localhost:9200/`| +|`APP_PROVIDER_WOPI_FOLDER_URL_PATH_TEMPLATE`| 1.0.0 |string|`Path template to navigate back from the app to the containing folder in the file list. Supported template variables are {{.ResourceInfo.ResourceID}}, {{.ResourceInfo.Mtime.Seconds}}, {{.ResourceInfo.Name}}, {{.ResourceInfo.Path}}, {{.ResourceInfo.Type}}, {{.ResourceInfo.Id.SpaceId}}, {{.ResourceInfo.Id.StorageId}}, {{.ResourceInfo.Id.OpaqueId}}, {{.ResourceInfo.MimeType}}`|`/f/{{.ResourceID}}`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_readme.mdx new file mode 100755 index 00000000..4481b9f1 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-provider_readme.mdx @@ -0,0 +1,41 @@ +--- +title: App Provider +date: 2026-01-15T10:35:01.388990849Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/app-provider +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `app-provider` service provides the CS3 App Provider API for OpenCloud. It is responsible for managing and serving applications that can open files based on their MIME types. + +The service works in conjunction with the `app-registry` service, which maintains the registry of available applications and their supported MIME types. When a client requests to open a file with a specific application, the `app-provider` service handles the request and coordinates with the application to provide the appropriate interface. + + +## Table of Contents + +* [Integration](#integration) +* [Configuration](#configuration) +* [Scalability](#scalability) + +## Integration + +The `app-provider` service integrates with: +- `app-registry` - For discovering which applications are available for specific MIME types +- `frontend` - The frontend service forwards app provider requests (default endpoint `/app`) to this service + +## Configuration + +The service can be configured via environment variables. Key configuration options include: +- `APP_PROVIDER_EXTERNAL_ADDR` - External address where the gateway service can reach the app provider + +## Scalability + +The app-provider service can be scaled horizontally as it primarily acts as a coordinator between applications and the OpenCloud backend services. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry.yaml new file mode 100644 index 00000000..5704e3af --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry.yaml @@ -0,0 +1,106 @@ +# Autogenerated +# Filename: app-registry.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9243 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9242 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +app_registry: + mimetypes: + - mime_type: application/pdf + extension: pdf + name: PDF + description: PDF document + icon: "" + default_app: "" + allow_creation: false + - mime_type: application/vnd.oasis.opendocument.text + extension: odt + name: OpenDocument + description: OpenDocument text document + icon: "" + default_app: "" + allow_creation: true + - mime_type: application/vnd.oasis.opendocument.spreadsheet + extension: ods + name: OpenSpreadsheet + description: OpenDocument spreadsheet document + icon: "" + default_app: "" + allow_creation: true + - mime_type: application/vnd.oasis.opendocument.presentation + extension: odp + name: OpenPresentation + description: OpenDocument presentation document + icon: "" + default_app: "" + allow_creation: true + - mime_type: application/vnd.openxmlformats-officedocument.wordprocessingml.document + extension: docx + name: Microsoft Word + description: Microsoft Word document + icon: "" + default_app: "" + allow_creation: true + - mime_type: application/vnd.openxmlformats-officedocument.wordprocessingml.form + extension: docxf + name: Form Document + description: Form Document + icon: "" + default_app: "" + allow_creation: true + - mime_type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet + extension: xlsx + name: Microsoft Excel + description: Microsoft Excel document + icon: "" + default_app: "" + allow_creation: true + - mime_type: application/vnd.openxmlformats-officedocument.presentationml.presentation + extension: pptx + name: Microsoft PowerPoint + description: Microsoft PowerPoint document + icon: "" + default_app: "" + allow_creation: true + - mime_type: application/vnd.jupyter + extension: ipynb + name: Jupyter Notebook + description: Jupyter Notebook + icon: "" + default_app: "" + allow_creation: false + - mime_type: text/markdown + extension: md + name: Markdown file + description: Markdown file + icon: "" + default_app: "" + allow_creation: true + - mime_type: application/compressed-markdown + extension: zmd + name: Compressed markdown file + description: Compressed markdown file + icon: "" + default_app: "" + allow_creation: false + - mime_type: application/vnd.geogebra.slides + extension: ggs + name: GeoGebra Slides + description: GeoGebra Slides + icon: "" + default_app: "" + allow_creation: false diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_configvars.mdx new file mode 100644 index 00000000..2b0c80d1 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_configvars.mdx @@ -0,0 +1,15 @@ +Environment variables for the **app-registry** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`APP_REGISTRY_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`APP_REGISTRY_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9243`| +|`APP_REGISTRY_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`APP_REGISTRY_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`APP_REGISTRY_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`APP_REGISTRY_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9242`| +|`OC_GRPC_PROTOCOL`
`APP_REGISTRY_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`OC_JWT_SECRET`
`APP_REGISTRY_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_readme.mdx new file mode 100755 index 00000000..dd9b3bb2 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/app-registry_readme.mdx @@ -0,0 +1,473 @@ +--- +title: App Registry +date: 2026-01-15T10:35:01.389149138Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/app-registry +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `app-registry` service is the single point where all apps register themselves and their respective supported mime types. + +Administrators can set default applications on a per MIME type basis and also allow the creation of new files for certain MIME types. This per MIME type configuration also features a description, file extension option and an icon. + + +## Table of Contents + +* [MIME Type Configuration / Creation Allow List](#mime-type-configuration-/-creation-allow-list) + * [MIME Type Configuration](#mime-type-configuration) +* [Endpoint Access](#endpoint-access) + * [Listing available apps and mime types](#listing-available-apps-and-mime-types) + * [Open a File With OpenCloud Web](#open-a-file-with-opencloud-web) + * [Open a File With the App Provider](#open-a-file-with-the-app-provider) + * [Creating a File With the App Provider](#creating-a-file-with-the-app-provider) + +## MIME Type Configuration / Creation Allow List + +The apps will register their supported MIME types automatically, so that users can open supported files with them. + +Administrators can set default applications for each MIME type and also allow the creation of new files for certain mime types. This, per MIME type configuration, also features a description, file extension option and an icon. + +### MIME Type Configuration + +Modifing the MIME type config can only be achieved via a yaml configuration. Using environment variables is not possible. The following is a brief structure and a field description: + +**Structure** + +```yaml +app_registry: + mimetypes: + - mime_type: application/vnd.oasis.opendocument.spreadsheet + extension: ods + name: OpenSpreadsheet + description: OpenDocument spreadsheet document + icon: https://some-website.test/opendocument-spreadsheet-icon.png + default_app: Collabora + allow_creation: true + - mime_type: ... +``` + +**Fields** + +* `mime_type`\ +The MIME type you want to configure. +* `extension`\ +The file extension to be used for new files. +* `name`\ +The name of the file / MIME type. +* `description`\ +The human-readable description of the file / MIME type. +* `icon`\ +The URL to an icon which should be used for that MIME type. +* `default_app`\ +The name of the default app which opens this MIME type if the user doesn’t specify one. +* `allow_creation`\ +Whether a user should be able to create new files of that MIME type (true or false). + +## Endpoint Access + +### Listing available apps and mime types + +Clients, for example OpenCloud Web, need to offer users the available apps to open files and mime types for new file creation. This information can be obtained from this endpoint. + +**Endpoint**: specified in the capabilities in `apps_url`, currently `/app/list` + +**Method**: HTTP GET + +**Authentication**: None + +**Request example**: + +```bash +curl 'https://opencloud.test/app/list' +``` + +**Response example**: + +HTTP status code: 200 + +```json +{ + "mime-types": [ + { + "mime_type": "application/pdf", + "ext": "pdf", + "app_providers": [ + { + "name": "OnlyOffice", + "icon": "https://some-website.test/onlyoffice-pdf-icon.png" + } + ], + "name": "PDF", + "description": "PDF document" + }, + { + "mime_type": "application/vnd.oasis.opendocument.text", + "ext": "odt", + "app_providers": [ + { + "name": "Collabora", + "icon": "https://some-website.test/collabora-odt-icon.png" + }, + { + "name": "OnlyOffice", + "icon": "https://some-website.test/onlyoffice-odt-icon.png" + } + ], + "name": "OpenDocument", + "icon": "https://some-website.test/opendocument-text-icon.png", + "description": "OpenDocument text document", + "allow_creation": true, + "default_application": "Collabora" + }, + { + "mime_type": "text/markdown", + "ext": "md", + "app_providers": [ + { + "name": "CodiMD", + "icon": "https://some-website.test/codimd-md-icon.png" + } + ], + "name": "Markdown file", + "description": "Markdown file", + "allow_creation": true, + "default_application": "CodiMD" + }, + { + "mime_type": "application/vnd.ms-word.document.macroenabled.12", + "app_providers": [ + { + "name": "Collabora", + "icon": "https://some-website.test/collabora-word-icon.png" + }, + { + "name": "OnlyOffice", + "icon": "https://some-website.test/onlyoffice-word-icon.png" + } + ] + }, + { + "mime_type": "application/vnd.ms-powerpoint.template.macroenabled.12", + "app_providers": [ + { + "name": "Collabora", + "icon": "https://some-website.test/collabora-powerpoint-icon.png" + } + ] + } + ] +} +``` + +### Open a File With OpenCloud Web + +**Endpoint**: specified in the capabilities in `open_web_url`, currently `/app/open-with-web` + +**Method**: HTTP POST + +**Authentication** (one of them): + +- `Authorization` header with OIDC Bearer token for authenticated users or basic auth credentials (if enabled in OpenCloud) +- `X-Access-Token` header with a REVA token for authenticated users + +**Query parameters**: + +- `file_id` (mandatory): id of the file to be opened +- `app_name` (optional) + - default (not given): default app for mime type + - possible values depend on the app providers for a mimetype from the `/app/open` endpoint + +**Request examples**: + +```bash +curl -X POST 'https://opencloud.test/app/open-with-web?file_id=ZmlsZTppZAo=' + +curl -X POST 'https://opencloud.test/app/open-with-web?file_id=ZmlsZTppZAo=&app_name=Collabora' +``` + +**Response examples**: + +The URI from the response JSON is intended to be opened with a GET request in a browser. If the user has not yet a session in the browser, a login flow is handled by OpenCloud Web. + +HTTP status code: 200 + +```json +{ + "uri": "https://....." +} +``` + +**Example responses (error case)**: + +See error cases for [Open a file with the app provider](#open-a-file-with-the-app-provider) + +### Open a File With the App Provider + +**Endpoint**: specified in the capabilities in `open_url`, currently `/app/open` + +**Method**: HTTP POST + +**Authentication** (one of them): + +- `Authorization` header with OIDC Bearer token for authenticated users or basic auth credentials (if enabled in OpenCloud) +- `Public-Token` header with public link token for public links +- `X-Access-Token` header with a REVA token for authenticated users + +**Query parameters**: + +- `file_id` (mandatory): id of the file to be opened +- `app_name` (optional) + - default (not given): default app for mime type + - possible values depend on the app providers for a mimetype from the `/app/open` endpoint +- `view_mode` (optional) + - default (not given): highest possible view mode, depending on the file permissions + - possible values: + - `write`: user can edit and download in the opening app + - `read`: user can view and download from the opening app + - `view`: user can view in the opening app (download is not possible) +- `lang` (optional) + - default (not given): default language of the application (which might maybe use the browser language) + - possible value is any ISO 639-1 language code. Examples: + - de + - en + - es + - ... + +**Request examples**: + +```bash +curl -X POST 'https://opencloud.test/app/open?file_id=ZmlsZTppZAo=' + +curl -X POST 'https://opencloud.test/app/open?file_id=ZmlsZTppZAo=&lang=de' + +curl -X POST 'https://opencloud.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora' + +curl -X POST 'https://opencloud.test/app/open?file_id=ZmlsZTppZAo=&view_mode=read' + +curl -X POST 'https://opencloud.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora&view_mode=write' +``` + +**Response examples**: + +All apps are expected to be opened in an iframe and the response will give some parameters for that action. + +There are apps, which need to be opened in the iframe with a form post. The form post must include all form parameters included in the response. For these apps the response will look like this: + +HTTP status code: 200 + +```json +{ + "app_url": "https://.....", + "method": "POST", + "form_parameters": { + "access_token": "eyJ0...", + "access_token_ttl": "1634300912000", + "arbitrary_param": "lorem-ipsum" + } +} +``` + +There are apps, which need to be opened in the iframe with a GET request. The GET request must have set all headers included in the response. For these apps the response will look like this: + +HTTP status code: 200 + +```json +{ + "app_url": "https://...", + "method": "GET", + "headers": { + "access_token": "eyJ0e...", + "access_token_ttl": "1634300912000", + "arbitrary_header": "lorem-ipsum" + } +} +``` + +**Example responses (error case)**: + +- missing `file_id` + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "missing file ID" + } + ``` + +- wrong `view_mode` + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "invalid view mode" + } + ``` + +- unknown `app_name` + + HTTP status code: 404 + + ```json + { + "code": "RESOURCE_NOT_FOUND", + "message": "error: not found: app 'Collabora' not found" + } + ``` + +- wrong / invalid file id + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "invalid file ID" + } + ``` + +- file id does not point to a file + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "the given file id does not point to a file" + } + ``` + +- file does not exist / unauthorized to open the file + + HTTP status code: 404 + + ```json + { + "code": "RESOURCE_NOT_FOUND", + "message": "file does not exist" + } + ``` + +- invalid language code + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "lang parameter does not contain a valid ISO 639-1 language code" + } + ``` + +### Creating a File With the App Provider + +**Endpoint**: specified in the capabilities in `new_file_url`, currently `/app/new` + +**Method**: HTTP POST + +**Authentication** (one of them): + +- `Authorization` header with OIDC Bearer token for authenticated users or basic auth credentials (if enabled in OpenCloud) +- `Public-Token` header with public link token for public links +- `X-Access-Token` header with a REVA token for authenticated users + +**Query parameters**: + +- `parent_container_id` (mandatory): ID of the folder in which the file will be created +- `filename` (mandatory): name of the new file +- `template` (optional): not yet implemented + +**Request examples**: + +```bash +curl -X POST 'https://opencloud.test/app/new?parent_container_id=c2lkOmNpZAo=&filename=test.odt' +``` + +**Response example**: + +You will receive a file id of the freshly created file, which you can use to open the file in an editor. + +```json +{ + "file_id": "ZmlsZTppZAo=" +} +``` + +**Example responses (error case)**: + +- missing `parent_container_id` + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "missing parent container ID" + } + ``` + +- missing `filename` + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "missing filename" + } + ``` + +- parent container not found + + HTTP status code: 404 + + ```json + { + "code": "RESOURCE_NOT_FOUND", + "message": "the parent container is not accessible or does not exist" + } + ``` + +- `parent_container_id` does not point to a container + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "the parent container id does not point to a container" + } + ``` + +- `filename` is invalid (e.g. includes a path segment) + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "the filename must not contain a path segment" + } + ``` + +- file already exists + + HTTP status code: 403 + + ```json + { + "code": "RESOURCE_ALREADY_EXISTS", + "message": "the file already exists" + } + ``` + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit.yaml new file mode 100644 index 00000000..1c6720df --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit.yaml @@ -0,0 +1,22 @@ +# Autogenerated +# Filename: audit.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9229 + token: "" + pprof: false + zpages: false +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" +auditlog: + log_to_console: true + log_to_file: false + filepath: "" + format: json diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_configvars.mdx new file mode 100644 index 00000000..1e941f06 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_configvars.mdx @@ -0,0 +1,20 @@ +Environment variables for the **audit** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`AUDIT_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`AUDIT_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9229`| +|`AUDIT_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`AUDIT_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`AUDIT_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`OC_EVENTS_ENDPOINT`
`AUDIT_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_CLUSTER`
`AUDIT_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`AUDIT_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`AUDIT_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided AUDIT_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`AUDIT_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_AUTH_USERNAME`
`AUDIT_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_AUTH_PASSWORD`
`AUDIT_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.`|``| +|`AUDIT_LOG_TO_CONSOLE`| 1.0.0 |bool|`Logs to stdout if set to 'true'. Independent of the LOG_TO_FILE option.`|`true`| +|`AUDIT_LOG_TO_FILE`| 1.0.0 |bool|`Logs to file if set to 'true'. Independent of the LOG_TO_CONSOLE option.`|`false`| +|`AUDIT_FILEPATH`| 1.0.0 |string|`Filepath of the logfile. Mandatory if LOG_TO_FILE is set to 'true'.`|``| +|`AUDIT_FORMAT`| 1.0.0 |string|`Log format. Supported values are '' (empty) and 'json'. Using 'json' is advised, '' (empty) renders the 'minimal' format. See the text description for more details.`|`json`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_readme.mdx new file mode 100755 index 00000000..fb77ac03 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/audit_readme.mdx @@ -0,0 +1,48 @@ +--- +title: Audit +date: 2026-01-15T10:35:01.389351759Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/audit +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The audit service logs all events of the system as an audit log. Per default, it will be logged to standard out, but can also be configured to a file output. Supported log formats are json or a minimal human-readable format. + +With audit logs, you are able to prove compliance with corporate guidelines as well as to enable reporting and auditing of operations. The audit service takes note of actions conducted by users and administrators. + +Example minimal format: +``` +file_delete) + user 'user_id' trashed file 'item_id' +file_trash_delete) + user 'user_id' removed file 'item_id' from trashbin +``` + +Example json: +``` +{"RemoteAddr":"","User":"user_id","URL":"","Method":"","UserAgent":"","Time":"","App":"admin_audit","Message":"user 'user_id' trashed file 'item_id'","Action":"file_delete","CLI":false,"Level":1,"Path":"path","Owner":"user_id","FileID":"item_id"} +{"RemoteAddr":"","User":"user_id","URL":"","Method":"","UserAgent":"","Time":"","App":"admin_audit","Message":"user 'user_id' removed file 'item_id' from trashbin","Action":"file_trash_delete","CLI":false,"Level":1,"Path":"path","Owner":"user_id","FileID":"item_id"} +``` + +The audit service is not started automatically when running as single binary started via `opencloud server` or when running as docker container and must be started and stopped manually on demand. + +The audit service logs: + +- File system operations +(create/delete/move; including actions on the trash bin and versioning) +- User management operations +(creation/deletion of users) +- Sharing operations +(user/group sharing, sharing via link, changing permissions, calls to sharing API from clients) + +## Table of Contents + + + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app.yaml new file mode 100644 index 00000000..80924043 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app.yaml @@ -0,0 +1,60 @@ +# Autogenerated +# Filename: auth-app.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9245 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9246 + tls: null + protocol: tcp +http: + addr: 127.0.0.1:9247 + root: / + cors: + allow_origins: + - '*' + allow_methods: + - GET + - POST + - DELETE + allow_headers: + - Authorization + - Origin + - Content-Type + - Accept + - X-Requested-With + - X-Request-Id + - Ocs-Apirequest + allow_credentials: true + tls: + enabled: false + cert: "" + key: "" +grpc_client_tls: null +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +skip_user_groups_in_token: false +machine_auth_api_key: "" +allow_impersonation: false +storage_driver: jsoncs3 +storage_drivers: + jsoncs3: + provider_addr: eu.opencloud.api.storage-system + system_user_id: "" + system_user_idp: internal + system_user_api_key: "" + password_generator: diceware + password_generator_options: + diceware: + number_of_words: 6 + randon: + password_length: 0 diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_configvars.mdx new file mode 100644 index 00000000..3f231a8d --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_configvars.mdx @@ -0,0 +1,35 @@ +Environment variables for the **auth-app** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`AUTH_APP_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`AUTH_APP_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9245`| +|`AUTH_APP_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`AUTH_APP_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`AUTH_APP_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing traces in-memory.`|`false`| +|`AUTH_APP_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9246`| +|`OC_GRPC_PROTOCOL`
`AUTH_APP_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`AUTH_APP_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9247`| +|`AUTH_APP_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/`| +|`OC_CORS_ALLOW_ORIGINS`
`AUTH_APP_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_CORS_ALLOW_METHODS`
`AUTH_APP_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_HEADERS`
`AUTH_APP_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_CREDENTIALS`
`AUTH_APP_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_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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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_JWT_SECRET`
`AUTH_APP_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`AUTH_APP_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the encoding of the user's group memberships in the access token. This reduces the token size, especially when users are members of a large number of groups.`|`false`| +|`OC_MACHINE_AUTH_API_KEY`
`AUTH_APP_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.`|``| +|`AUTH_APP_ENABLE_IMPERSONATION`| 1.0.0 |bool|`Allows admins to create app tokens for other users. Used for migration. Do NOT use in productive deployments.`|`false`| +|`AUTH_APP_STORAGE_DRIVER`| 4.0.0 |string|`Driver to be used to persist the app tokes . Supported values are 'jsoncs3', 'json'.`|`jsoncs3`| +|`AUTH_APP_JSONCS3_PROVIDER_ADDR`| 4.0.0 |string|`GRPC address of the STORAGE-SYSTEM service.`|`eu.opencloud.api.storage-system`| +|`OC_SYSTEM_USER_ID`
`AUTH_APP_JSONCS3_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`
`AUTH_APP_JSONCS3_SYSTEM_USER_IDP`| 4.0.0 |string|`IDP of the OpenCloud STORAGE-SYSTEM system user.`|`internal`| +|`OC_SYSTEM_USER_API_KEY`
`AUTH_APP_JSONCS3_SYSTEM_USER_API_KEY`| 4.0.0 |string|`API key for the STORAGE-SYSTEM system user.`|``| +|`AUTH_APP_JSONCS3_PASSWORD_GENERATOR`| 4.0.0 |string|`The password generator that should be used for generating app tokens. Supported values are: 'diceware' and 'random'.`|`diceware`| +|`AUTH_APP_JSONCS3_DICEWARE_NUMBER_OF_WORDS`| 4.0.0 |int|`The number of words the generated passphrase will have.`|`6`| +|`AUTH_APP_JSONCS3_RANDOM_PASSWORD_LENGTH`| 4.0.0 |int|`The number of charactors the generated passwords will have.`|`0`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_readme.mdx new file mode 100755 index 00000000..81a45c82 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-app_readme.mdx @@ -0,0 +1,164 @@ +--- +title: Auth-App +date: 2026-01-15T10:35:01.389495469Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/auth-app +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The auth-app service provides authentication for 3rd party apps unable to use +OpenID Connect. The service is enabled by default and started automatically. It +is possible to disable the service by setting: + +```bash +OC_EXCLUDE_RUN_SERVICES=auth-app # deployment specific. Removes service from the list of automatically started services, use with single-binary deployments +PROXY_ENABLE_APP_AUTH=false # mandatory, disables app authentication. In case of a distributed environment, this envvar needs to be set in the proxy service. +``` + + +## Table of Contents + +* [App Tokens](#app-tokens) +* [Important Security Note](#important-security-note) +* [Managing App Tokens](#managing-app-tokens) + * [Via API](#via-api) + * [Via Impersonation API](#via-impersonation-api) + * [Via CLI (developer only)](#via-cli-(developer-only)) +* [Authenticating using App Tokens](#authenticating-using-app-tokens) + +## App Tokens + +App Tokens are password specifically generated to be used by 3rd party applications +for authentication when accessing the OpenCloud API endpoints. To +be able to use an app token, one must first create a token. There are different +options of creating a token. + +## Important Security Note + +When using an external IDP for authentication, App Token are NOT invalidated +when the user is disabled or locked in that external IDP. That means the user +will still be able to use its existing App Tokens for authentication for as +long as the App Tokes are valid. + +## Managing App Tokens + +### Via API + +Please note: This API is preliminary. In the future we will provide endpoints +in the `graph` service for allowing the management of App Tokens. + +The `auth-app` service provides an API to create (POST), list (GET) and delete (DELETE) tokens at the `/auth-app/tokens` endpoint. + +* **Create a token**\ + The POST request requires: + * A `expiry` key/value pair in the form of `expiry=`\ + Example: `expiry=72h` + ```bash + curl --request POST 'https:///auth-app/tokens?expiry={value}' \ + --header 'accept: application/json' + ``` + Example output: + ``` + { + "token": "3s2K7816M4vuSpd5", + "expiration_date": "2024-08-08T13:42:42.796888022+02:00", + "created_date": "2024-08-07T13:42:42+02:00", + "label": "Generated via API" + } + ``` + + Note, that this is the only time the app token will be returned in cleartext. To use the token + please copy it from the response. + +* **List tokens**\ + ```bash + curl --request GET 'https:///auth-app/tokens' \ + --header 'accept: application/json' + ``` + + Note that the `token` value in the response to the "List Tokens` request is not the actual + app token, but the UUID of the token. So this value cannot be used for authenticating + with the token. + + Example output: + ``` + [ + { + "token": "155f402e-1c5c-411c-92d4-92f3b612cd99" + "expiration_date": "2024-08-08T13:44:31.025199075+02:00", + "created_date": "2024-08-07T13:44:31+02:00", + "label": "Generated via Impersonation API" + }, + { + "token": "8c606bdb-e22e-4094-9304-732fd4702bc9" + "expiration_date": "2024-08-08T13:46:41.936052281+02:00", + "created_date": "2024-08-07T13:46:42+02:00", + "label": "Generated via Impersonation API" + } + ] + ``` + +* **Delete a token**\ + The DELETE request requires: + * A `token` key/value pair in the form of `token=`. The value needs to be the hashed value as returned by the `List Tokens` respone.\ + Example: `token=8c606bdb-e22e-4094-9304-732fd4702bc9` + ```bash + curl --request DELETE 'https:///auth-app/tokens?token={value}' \ + --header 'accept: application/json' + ``` + +### Via Impersonation API + +When setting the environment variable `AUTH_APP_ENABLE_IMPERSONATION` to +`true`, admins will be able to use the `/auth-app/tokens` endpoint to create +tokens for other users. This can be important for migration scenarios, but +should not be considered for regular tasks on a production system for security +reasons. + +To impersonate, the respective requests from the CLI commands above extend with +the following parameters, where you can use one or the other: + +* The `userID` in the form of: `userID={value}`\ + Example:\ + `userID=4c510ada- ... -42cdf82c3d51` + +* The `userName` in the form of: `userName={value}`\ + Example:\ + `userName=alan` + +Example:\ +A final create request would then look like: +```bash +curl --request POST 'https:///auth-app/tokens?expiry={value}&userName={value}' \ + --header 'accept: application/json' +``` + +### Via CLI (developer only) + +As the CLI is using the internal CS3Apis this needs access to the reva gateway +service. This is mainly of developer (and admin) usage. +Replace the `user-name` with an existing user. For the `token-expiration`, you +can use any time abbreviation from the following list: `h, m, s`. Examples: +`72h` or `1h` or `1m` or `1s.` Default is `72h`. + +```bash +opencloud auth-app create --user-name={user-name} --expiration={token-expiration} +``` + +## Authenticating using App Tokens + +To autenticate using an App Token simply use the username for which token was generated +and the token value as returned by the "Create Token" request. + +```bash +curl -u : 'https:///graph/v1.0/me' \ + --header 'accept: application/json' +``` + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic.yaml new file mode 100644 index 00000000..66f7ae96 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic.yaml @@ -0,0 +1,67 @@ +# Autogenerated +# Filename: auth-basic.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9147 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9146 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +skip_user_groups_in_token: false +auth_provider: ldap +auth_providers: + ldap: + uri: ldaps://localhost:9235 + ca_cert: /root/.opencloud/idm/ldap.crt + insecure: false + bind_dn: uid=reva,ou=sysusers,o=libregraph-idm + bind_password: "" + user_base_dn: ou=users,o=libregraph-idm + group_base_dn: ou=groups,o=libregraph-idm + user_scope: sub + group_scope: sub + user_filter: "" + group_filter: "" + user_object_class: inetOrgPerson + group_object_class: groupOfNames + login_attributes: + - uid + idp: https://localhost:9200 + disable_user_mechanism: attribute + ldap_disabled_users_group_dn: cn=DisabledUsersGroup,ou=groups,o=libregraph-idm + user_schema: + id: openCloudUUID + tenant_id: "" + id_is_octet_string: false + mail: mail + display_name: displayname + user_name: uid + user_enabled: openCloudUserEnabled + group_schema: + id: openCloudUUID + id_is_octet_string: false + mail: mail + display_name: cn + group_name: cn + member: member + owncloudsql: + db_username: owncloud + db_password: "" + db_host: mysql + db_port: 3306 + db_name: owncloud + idp: https://localhost:9200 + nobody: 90 + join_username: false + join_owncloud_uuid: false diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_configvars.mdx new file mode 100644 index 00000000..04770fcc --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_configvars.mdx @@ -0,0 +1,56 @@ +Environment variables for the **auth-basic** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`AUTH_BASIC_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`AUTH_BASIC_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9147`| +|`AUTH_BASIC_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`AUTH_BASIC_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`AUTH_BASIC_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing traces in-memory.`|`false`| +|`AUTH_BASIC_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9146`| +|`OC_GRPC_PROTOCOL`
`AUTH_BASIC_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`OC_JWT_SECRET`
`AUTH_BASIC_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`AUTH_BASIC_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the encoding of the user's group memberships in the reva access token. This reduces the token size, especially when users are members of a large number of groups.`|`false`| +|`AUTH_BASIC_AUTH_MANAGER`| 1.0.0 |string|`The authentication manager to check if credentials are valid. Supported value is 'ldap'.`|`ldap`| +|`OC_LDAP_URI`
`AUTH_BASIC_LDAP_URI`| 1.0.0 |string|`URI of the LDAP Server to connect to. Supported URI schemes are 'ldaps://' and 'ldap://'`|`ldaps://localhost:9235`| +|`OC_LDAP_CACERT`
`AUTH_BASIC_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.`|`/root/.opencloud/idm/ldap.crt`| +|`OC_LDAP_INSECURE`
`AUTH_BASIC_LDAP_INSECURE`| 1.0.0 |bool|`Disable TLS certificate validation for the LDAP connections. Do not set this in production environments.`|`false`| +|`OC_LDAP_BIND_DN`
`AUTH_BASIC_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`
`AUTH_BASIC_LDAP_BIND_PASSWORD`| 1.0.0 |string|`Password to use for authenticating the 'bind_dn'.`|``| +|`OC_LDAP_USER_BASE_DN`
`AUTH_BASIC_LDAP_USER_BASE_DN`| 1.0.0 |string|`Search base DN for looking up LDAP users.`|`ou=users,o=libregraph-idm`| +|`OC_LDAP_GROUP_BASE_DN`
`AUTH_BASIC_LDAP_GROUP_BASE_DN`| 1.0.0 |string|`Search base DN for looking up LDAP groups.`|`ou=groups,o=libregraph-idm`| +|`OC_LDAP_USER_SCOPE`
`AUTH_BASIC_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_GROUP_SCOPE`
`AUTH_BASIC_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_USER_FILTER`
`AUTH_BASIC_LDAP_USER_FILTER`| 1.0.0 |string|`LDAP filter to add to the default filters for user search like '(objectclass=openCloudUser)'.`|``| +|`OC_LDAP_GROUP_FILTER`
`AUTH_BASIC_LDAP_GROUP_FILTER`| 1.0.0 |string|`LDAP filter to add to the default filters for group searches.`|``| +|`OC_LDAP_USER_OBJECTCLASS`
`AUTH_BASIC_LDAP_USER_OBJECTCLASS`| 1.0.0 |string|`The object class to use for users in the default user search filter ('inetOrgPerson').`|`inetOrgPerson`| +|`OC_LDAP_GROUP_OBJECTCLASS`
`AUTH_BASIC_LDAP_GROUP_OBJECTCLASS`| 1.0.0 |string|`The object class to use for groups in the default group search filter ('groupOfNames').`|`groupOfNames`| +|`LDAP_LOGIN_ATTRIBUTES`
`AUTH_BASIC_LDAP_LOGIN_ATTRIBUTES`| 1.0.0 |[]string|`A list of user object attributes that can be used for login. See the Environment Variable Types description for more details.`|`[uid]`| +|`OC_URL`
`OC_OIDC_ISSUER`
`AUTH_BASIC_IDP_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_LDAP_DISABLE_USER_MECHANISM`
`AUTH_BASIC_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_DISABLED_USERS_GROUP_DN`
`AUTH_BASIC_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_USER_SCHEMA_ID`
`AUTH_BASIC_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_TENANT_ID`
`AUTH_BASIC_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_ID_IS_OCTETSTRING`
`AUTH_BASIC_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`
`AUTH_BASIC_LDAP_USER_SCHEMA_MAIL`| 1.0.0 |string|`LDAP Attribute to use for the email address of users.`|`mail`| +|`OC_LDAP_USER_SCHEMA_DISPLAYNAME`
`AUTH_BASIC_LDAP_USER_SCHEMA_DISPLAYNAME`| 1.0.0 |string|`LDAP Attribute to use for the displayname of users.`|`displayname`| +|`OC_LDAP_USER_SCHEMA_USERNAME`
`AUTH_BASIC_LDAP_USER_SCHEMA_USERNAME`| 1.0.0 |string|`LDAP Attribute to use for username of users.`|`uid`| +|`OC_LDAP_USER_ENABLED_ATTRIBUTE`
`AUTH_BASIC_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_GROUP_SCHEMA_ID`
`AUTH_BASIC_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`
`AUTH_BASIC_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_MAIL`
`AUTH_BASIC_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_DISPLAYNAME`
`AUTH_BASIC_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`
`AUTH_BASIC_LDAP_GROUP_SCHEMA_GROUPNAME`| 1.0.0 |string|`LDAP Attribute to use for the name of groups.`|`cn`| +|`OC_LDAP_GROUP_SCHEMA_MEMBER`
`AUTH_BASIC_LDAP_GROUP_SCHEMA_MEMBER`| 1.0.0 |string|`LDAP Attribute that is used for group members.`|`member`| +|`AUTH_BASIC_OWNCLOUDSQL_DB_USERNAME`| 1.0.0 |string|`Database user to use for authenticating with the owncloud database.`|`owncloud`| +|`AUTH_BASIC_OWNCLOUDSQL_DB_PASSWORD`| 1.0.0 |string|`Password for the database user.`|``| +|`AUTH_BASIC_OWNCLOUDSQL_DB_HOST`| 1.0.0 |string|`Hostname of the database server.`|`mysql`| +|`AUTH_BASIC_OWNCLOUDSQL_DB_PORT`| 1.0.0 |int|`Network port to use for the database connection.`|`3306`| +|`AUTH_BASIC_OWNCLOUDSQL_DB_NAME`| 1.0.0 |string|`Name of the owncloud database.`|`owncloud`| +|`AUTH_BASIC_OWNCLOUDSQL_IDP`| 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`| +|`AUTH_BASIC_OWNCLOUDSQL_NOBODY`| 1.0.0 |int64|`Fallback number if no numeric UID and GID properties are provided.`|`90`| +|`AUTH_BASIC_OWNCLOUDSQL_JOIN_USERNAME`| 1.0.0 |bool|`Join the user properties table to read usernames`|`false`| +|`AUTH_BASIC_OWNCLOUDSQL_JOIN_OWNCLOUD_UUID`| 1.0.0 |bool|`Join the user properties table to read user ID's.`|`false`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_readme.mdx new file mode 100755 index 00000000..bec46157 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-basic_readme.mdx @@ -0,0 +1,56 @@ +--- +title: Auth-Basic +date: 2026-01-15T10:35:01.389761218Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/auth-basic +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The OpenCloud Auth Basic service provides basic authentication for those clients who cannot handle OpenID Connect. This should only be enabled for tests and development. + +The `auth-basic` service is responsible for validating authentication of incoming requests. To do so, it will use the configured `auth manager`, see the `Auth Managers` section. Only HTTP basic auth requests to OpenCloud will involve the `auth-basic` service. + +To enable `auth-basic`, you first must set `PROXY_ENABLE_BASIC_AUTH` to `true`. + + +## Table of Contents + +* [The `auth` Service Family](#the-`auth`-service-family) +* [Auth Managers](#auth-managers) + * [LDAP Auth Manager](#ldap-auth-manager) + * [Other Auth Managers](#other-auth-managers) +* [Scalability](#scalability) + +## The `auth` Service Family + +OpenCloud uses serveral authentication services for different use cases. All services that start with `auth-` are part of the authentication service family. Each member authenticates requests with different scopes. As of now, these services exist: + - `auth-app` handles authentication of external 3rd party apps + - `auth-basic` handles basic authentication + - `auth-bearer` handles oidc authentication + - `auth-machine` handles interservice authentication when a user is impersonated + - `auth-service` handles interservice authentication when using service accounts + +## Auth Managers + +Since the `auth-basic` service does not do any validation itself, it needs to be configured with an authentication manager. One can use the `AUTH_BASIC_AUTH_MANAGER` environment variable to configure this. Currently only one auth manager is supported: `"ldap"` + +### LDAP Auth Manager + +Setting `AUTH_BASIC_AUTH_MANAGER` to `"ldap"` will configure the `auth-basic` service to use LDAP as auth manager. This is the recommended option for running in a production and testing environment. More details on how to configure LDAP with OpenCloud can be found in the admin docs. + +### Other Auth Managers + +OpenCloud currently supports no other auth manager + +## Scalability + +When using `"ldap"` as auth manager, there is no persistance as requests will just be forwarded to the LDAP server. Therefore, multiple instances of the `auth-basic` service can be started without further configuration. Be aware, that other auth managers might not allow that. + + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer.yaml new file mode 100644 index 00000000..f7e28e0e --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer.yaml @@ -0,0 +1,27 @@ +# Autogenerated +# Filename: auth-bearer.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9149 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9148 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +skip_user_groups_in_token: false +oidc: + issuer: https://localhost:9200 + insecure: false + id_claim: preferred_username + uid_claim: "" + gid_claim: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_configvars.mdx new file mode 100644 index 00000000..04f21df1 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_configvars.mdx @@ -0,0 +1,21 @@ +Environment variables for the **auth-bearer** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`AUTH_BEARER_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`AUTH_BEARER_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9149`| +|`AUTH_BEARER_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`AUTH_BEARER_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`AUTH_BEARER_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`AUTH_BEARER_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9148`| +|`OC_GRPC_PROTOCOL`
`AUTH_BEARER_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`OC_JWT_SECRET`
`AUTH_BEARER_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`AUTH_BEARER_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the encoding of the user's group memberships in the reva access token. This reduces the token size, especially when users are members of a large number of groups.`|`false`| +|`OC_URL`
`OC_OIDC_ISSUER`
`AUTH_BEARER_OIDC_ISSUER`| 1.0.0 |string|`URL of the OIDC issuer. It defaults to URL of the builtin IDP.`|`https://localhost:9200`| +|`OC_INSECURE`
`AUTH_BEARER_OIDC_INSECURE`| 1.0.0 |bool|`Allow insecure connections to the OIDC issuer.`|`false`| +|`AUTH_BEARER_OIDC_ID_CLAIM`| 1.0.0 |string|`Name of the claim, which holds the user identifier.`|`preferred_username`| +|`AUTH_BEARER_OIDC_UID_CLAIM`| 1.0.0 |string|`Name of the claim, which holds the UID.`|``| +|`AUTH_BEARER_OIDC_GID_CLAIM`| 1.0.0 |string|`Name of the claim, which holds the GID.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_readme.mdx new file mode 100755 index 00000000..d947e932 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-bearer_readme.mdx @@ -0,0 +1,43 @@ +--- +title: Auth-Bearer +date: 2026-01-15T10:35:01.389898118Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/auth-bearer +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The OpenCloud Auth Bearer service communicates with the configured OpenID Connect identity provider to authenticate requests. OpenID Connect is the default authentication mechanism for all clients: web, desktop and mobile. Basic auth is only used for testing and has to be explicity enabled. + + +## Table of Contents + +* [The `auth` Service Family](#the-`auth`-service-family) +* [Built in OpenID Connect Identity Provider](#built-in-openid-connect-identity-provider) +* [Scalability](#scalability) + +## The `auth` Service Family + +OpenCloud uses serveral authentication services for different use cases. All services that start with `auth-` are part of the authentication service family. Each member authenticates requests with different scopes. As of now, these services exist: + - `auth-app` handles authentication of external 3rd party apps + - `auth-basic` handles basic authentication + - `auth-bearer` handles oidc authentication + - `auth-machine` handles interservice authentication when a user is impersonated + - `auth-service` handles interservice authentication when using service accounts + +## Built in OpenID Connect Identity Provider + +A default OpenCloud deployment will start a [built in OpenID Connect identity provider](https://github.com/opencloud-eu/opencloud/tree/main/services/idp) but can be configured to use an external one as well. + +## Scalability + +There is no persistance or caching. The proxy caches verified auth bearer tokens. Requests will be forwarded to the identity provider. Therefore, multiple instances of the `auth-bearer` service can be started without further configuration. Currently, the auth registry used by the gateway can only use a single instance of the service. To use more than one auth provider per deployment you need to scale the gateway. + +This will change when we use the service registry in more places and use micro clients to select an instance of a service. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine.yaml new file mode 100644 index 00000000..fe028702 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine.yaml @@ -0,0 +1,22 @@ +# Autogenerated +# Filename: auth-machine.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9167 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9166 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +skip_user_groups_in_token: false +machine_auth_api_key: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_configvars.mdx new file mode 100644 index 00000000..fd1cc414 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_configvars.mdx @@ -0,0 +1,17 @@ +Environment variables for the **auth-machine** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`AUTH_MACHINE_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`AUTH_MACHINE_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9167`| +|`AUTH_MACHINE_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`AUTH_MACHINE_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`AUTH_MACHINE_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`AUTH_MACHINE_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9166`| +|`OC_GRPC_PROTOCOL`
`AUTH_MACHINE_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`OC_JWT_SECRET`
`AUTH_MACHINE_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`AUTH_MACHINE_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the encoding of the user's group memberships in the reva access token. This reduces the token size, especially when users are members of a large number of groups.`|`false`| +|`OC_MACHINE_AUTH_API_KEY`
`AUTH_MACHINE_API_KEY`| 1.0.0 |string|`Machine auth API key used to validate internal requests necessary for the access to resources from other services.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_readme.mdx new file mode 100755 index 00000000..42bbf350 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-machine_readme.mdx @@ -0,0 +1,38 @@ +--- +title: Auth-Machine +date: 2026-01-15T10:35:01.389999337Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/auth-machine +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The OpenCloud Auth Machine is used for interservice communication when using user impersonation. + +OpenCloud uses serveral authentication services for different use cases. All services that start with `auth-` are part of the authentication service family. Each member authenticates requests with different scopes. As of now, these services exist: + - `auth-app` handles authentication of external 3rd party apps + - `auth-basic` handles basic authentication + - `auth-bearer` handles oidc authentication + - `auth-machine` handles interservice authentication when a user is impersonated + - `auth-service` handles interservice authentication when using service accounts + + +## Table of Contents + +* [User Impersonation](#user-impersonation) +* [Deprecation](#deprecation) + +## User Impersonation + +When one OpenCloud service is trying to talk to other OpenCloud services, it needs to authenticate itself. To do so, it will impersonate a user using the `auth-machine` service. It will then act on behalf of this user. Any action will show up as action of this specific user, which gets visible when e.g. logged in the audit log. + +## Deprecation + +With the upcoming `auth-service` service, the `auth-machine` service will be used less frequently and is probably a candidate for deprecation. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service.yaml new file mode 100644 index 00000000..e1cd9551 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service.yaml @@ -0,0 +1,23 @@ +# Autogenerated +# Filename: auth-service.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9198 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9199 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +service_account: + service_account_id: "" + service_account_secret: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_configvars.mdx new file mode 100644 index 00000000..dab87e73 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_configvars.mdx @@ -0,0 +1,17 @@ +Environment variables for the **auth-service** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`AUTH_SERVICE_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`AUTH_SERVICE_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9198`| +|`AUTH_SERVICE_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`AUTH_SERVICE_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`AUTH_SERVICE_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`AUTH_SERVICE_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9199`| +|`OC_GRPC_PROTOCOL`
`AUTH_SERVICE_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`OC_JWT_SECRET`
`AUTH_SERVICE_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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_SERVICE_ACCOUNT_ID`
`AUTH_SERVICE_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`
`AUTH_SERVICE_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_readme.mdx new file mode 100755 index 00000000..c3ffc60b --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/auth-service_readme.mdx @@ -0,0 +1,41 @@ +--- +title: Auth-Service +date: 2026-01-15T10:35:01.390106797Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/auth-service +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The OpenCloud Auth Service is used to authenticate service accounts. Compared to normal accounts, service accounts are OpenCloud internal only and not available as ordinary users like via LDAP. + + +## Table of Contents + +* [The `auth` Service Family](#the-`auth`-service-family) +* [Service Accounts](#service-accounts) +* [Configuring Service Accounts](#configuring-service-accounts) + +## The `auth` Service Family + +OpenCloud uses serveral authentication services for different use cases. All services that start with `auth-` are part of the authentication service family. Each member authenticates requests with different scopes. As of now, these services exist: + - `auth-app` handles authentication of external 3rd party apps + - `auth-basic` handles basic authentication + - `auth-bearer` handles oidc authentication + - `auth-machine` handles interservice authentication when a user is impersonated + - `auth-service` handles interservice authentication when using service accounts + +## Service Accounts + +Service accounts are user accounts that are only used for inter service communication. The users have no personal space, do not show up in user lists and cannot login via the UI. Service accounts can be configured in the settings service. Only the `admin` service user is available for now. Additionally to the actions it can do via its role, all service users can stat all files on all spaces. + +## Configuring Service Accounts + +By using the envvars `OC_SERVICE_ACCOUNT_ID` and `OC_SERVICE_ACCOUNT_SECRET`, one can configure the ID and the secret of the service user. The secret can be rotated regulary to increase security. For activating a new secret, all services where the envvars are used need to be restarted. The secret is always and only stored in memory and never written into any persistant store. Though you can use any string for the service account, it is recommmended to use a UUIDv4 string. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog.yaml new file mode 100644 index 00000000..283a4b23 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog.yaml @@ -0,0 +1,24 @@ +# Autogenerated +# Filename: clientlog.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9260 + token: "" + pprof: false + zpages: false +grpc_client_tls: null +token_manager: + jwt_secret: "" +reva_gateway: eu.opencloud.api.gateway +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" +service_account: + service_account_id: "" + service_account_secret: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_configvars.mdx new file mode 100644 index 00000000..f7bbc80b --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_configvars.mdx @@ -0,0 +1,20 @@ +Environment variables for the **clientlog** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`CLIENTLOG_USERLOG_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`CLIENTLOG_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9260`| +|`CLIENTLOG_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`CLIENTLOG_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`CLIENTLOG_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`OC_JWT_SECRET`
`CLIENTLOG_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`CS3 gateway used to look up user metadata`|`eu.opencloud.api.gateway`| +|`OC_EVENTS_ENDPOINT`
`CLIENTLOG_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_CLUSTER`
`CLIENTLOG_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`CLIENTLOG_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`CLIENTLOG_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided NOTIFICATIONS_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`CLIENTLOG_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_AUTH_USERNAME`
`CLIENTLOG_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_AUTH_PASSWORD`
`CLIENTLOG_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_SERVICE_ACCOUNT_ID`
`CLIENTLOG_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`
`CLIENTLOG_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_readme.mdx new file mode 100755 index 00000000..6c6b7f29 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/clientlog_readme.mdx @@ -0,0 +1,34 @@ +--- +title: Clientlog Service +date: 2026-01-15T10:35:01.390272837Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/clientlog +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `clientlog` service is responsible for composing machine readable notifications for clients. Clients are apps and web interfaces. + + +## Table of Contents + +* [The Log Service Ecosystem](#the-log-service-ecosystem) +* [Clientlog Events](#clientlog-events) + +## The Log Service Ecosystem + +Log services like the `userlog`, `clientlog` and `sse` are responsible for composing notifications for a certain audience. + - The `userlog` service translates and adjusts messages to be human readable. + - The `clientlog` service composes machine readable messages, so clients can act without the need to query the server. + - The `sse` service is only responsible for sending these messages. It does not care about their form or language. + +## Clientlog Events + +The messages the `clientlog` service sends are intended for the use by clients, not by users. The client might for example be informed that a file has finished post-processing. With that, the client can make the file available to the user without additional server queries. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration.yaml new file mode 100644 index 00000000..f0f67838 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration.yaml @@ -0,0 +1,54 @@ +# Autogenerated +# Filename: collaboration.yaml + +app: + name: Collabora + product: "" + description: Open office documents with Collabora + icon: image-edit + addr: https://127.0.0.1:9980 + insecure: false + proofkeys: + disable: false + duration: 12h + licensecheckenable: false +store: + store: nats-js-kv + nodes: + - 127.0.0.1:9233 + database: collaboration + table: "" + ttl: 30m0s + username: "" + password: "" +token_manager: + jwt_secret: "" +grpc: + addr: 127.0.0.1:9301 + protocol: tcp +http: + addr: 127.0.0.1:9300 + tls: + enabled: false + cert: "" + key: "" +wopi: + wopisrc: https://localhost:9300 + secret: "" + disable_chat: false + proxy_url: "" + proxy_secret: "" + short_tokens: false +cs3api: + gateway: + name: eu.opencloud.api.gateway + datagateway: + insecure: false + grpc_client_tls: null + app_registration_interval: 30s +loglevel: error +debug: + addr: 127.0.0.1:9304 + token: "" + pprof: false + zpages: false diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_configvars.mdx new file mode 100644 index 00000000..4dbed3be --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_configvars.mdx @@ -0,0 +1,42 @@ +Environment variables for the **collaboration** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`COLLABORATION_SERVICE_NAME`| 3.6.0 |string|`The name of the service which is registered. You only need to change this when more than one collaboration service is needed.`|`collaboration`| +|`COLLABORATION_APP_NAME`| 1.0.0 |string|`The name of the app which is shown to the user. You can chose freely but you are limited to a single word without special characters or whitespaces. We recommend to use pascalCase like 'CollaboraOnline'.`|`Collabora`| +|`COLLABORATION_APP_PRODUCT`| 1.0.0 |string|`The WebOffice app, either Collabora, OnlyOffice, Microsoft365 or MicrosoftOfficeOnline.`|``| +|`COLLABORATION_APP_DESCRIPTION`| 1.0.0 |string|`App description`|`Open office documents with Collabora`| +|`COLLABORATION_APP_ICON`| 1.0.0 |string|`Icon for the app`|`image-edit`| +|`COLLABORATION_APP_ADDR`| 1.0.0 |string|`The URL where the WOPI app is located, such as \https://127.0.0.1:8080.`|`https://127.0.0.1:9980`| +|`COLLABORATION_APP_INSECURE`| 1.0.0 |bool|`Skip TLS certificate verification when connecting to the WOPI app`|`false`| +|`COLLABORATION_APP_PROOF_DISABLE`| 1.0.0 |bool|`Disable the proof keys verification`|`false`| +|`COLLABORATION_APP_PROOF_DURATION`| 1.0.0 |string|`Duration for the proof keys to be cached in memory, using time.ParseDuration format. If the duration can't be parsed, we'll use the default 12h as duration`|`12h`| +|`COLLABORATION_APP_LICENSE_CHECK_ENABLE`| 1.0.0 |bool|`Enable license checking to edit files. Needs to be enabled when using Microsoft365 with the business flow.`|`false`| +|`OC_PERSISTENT_STORE`
`COLLABORATION_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_NODES`
`COLLABORATION_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]`| +|`COLLABORATION_STORE_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`collaboration`| +|`COLLABORATION_STORE_TABLE`| 1.0.0 |string|`The database table the store should use.`|``| +|`OC_PERSISTENT_STORE_TTL`
`COLLABORATION_STORE_TTL`| 1.0.0 |Duration|`Time to live for events in the store. Defaults to '30m' (30 minutes). See the Environment Variable Types description for more details.`|`30m0s`| +|`OC_PERSISTENT_STORE_AUTH_USERNAME`
`COLLABORATION_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_AUTH_PASSWORD`
`COLLABORATION_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_JWT_SECRET`
`COLLABORATION_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`COLLABORATION_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9301`| +|`OC_GRPC_PROTOCOL`
`COLLABORATION_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`COLLABORATION_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9300`| +|`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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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.`|``| +|`COLLABORATION_WOPI_SRC`| 1.0.0 |string|`The WOPI source base URL containing schema, host and port. Set this to the schema and domain where the collaboration service is reachable for the wopi app, such as \https://office.example.test.`|`https://localhost:9300`| +|`COLLABORATION_WOPI_SECRET`| 1.0.0 |string|`Used to mint and verify WOPI JWT tokens and encrypt and decrypt the REVA JWT token embedded in the WOPI JWT token.`|``| +|`COLLABORATION_WOPI_DISABLE_CHAT`
`OC_WOPI_DISABLE_CHAT`| 1.0.0 |bool|`Disable chat in the office web frontend. This feature applies to OnlyOffice and Microsoft.`|`false`| +|`COLLABORATION_WOPI_PROXY_URL`| 1.0.0 |string|`The URL to the OpenCloud WOPI proxy. Optional. To use this feature, you need an office365 proxy subscription. If you become part of the Microsoft CSP program (\https://learn.microsoft.com/en-us/partner-center/enroll/csp-overview), you can use WebOffice without a proxy.`|``| +|`COLLABORATION_WOPI_PROXY_SECRET`| 1.0.0 |string|`Optional, the secret to authenticate against the OpenCloud WOPI proxy. This secret can be obtained from OpenCloud via the office365 proxy subscription.`|``| +|`COLLABORATION_WOPI_SHORTTOKENS`| 1.0.0 |bool|`Use short access tokens for WOPI access. This is useful for office packages, like Microsoft Office Online, which have URL length restrictions. If enabled, a persistent store must be configured.`|`false`| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`CS3 gateway used to look up user metadata.`|`eu.opencloud.api.gateway`| +|`COLLABORATION_CS3API_DATAGATEWAY_INSECURE`| 1.0.0 |bool|`Connect to the CS3API data gateway insecurely.`|`false`| +|`COLLABORATION_CS3API_APP_REGISTRATION_INTERVAL`| 4.0.0 |Duration|`The interval at which the app provider registers itself.`|`30s`| +|`OC_LOG_LEVEL`
`COLLABORATION_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`COLLABORATION_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9304`| +|`COLLABORATION_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`COLLABORATION_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`COLLABORATION_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_readme.mdx new file mode 100755 index 00000000..eef69353 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/collaboration_readme.mdx @@ -0,0 +1,91 @@ +--- +title: Collaboration +date: 2026-01-15T10:35:01.390391566Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/collaboration +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The collaboration service connects opencloud with document servers such as Collabora, ONLYOFFICE or Microsoft using the WOPI protocol. + +Since this service requires an external document server, it won't start by default when using `opencloud server`. You must start it manually with the `opencloud collaboration server` command. + +Because the collaboration service needs to be started manually, the following prerequisite applies: On collaboration service startup, particular environment variables are required to be populated. If environment variables have a default like the `MICRO_REGISTRY_ADDRESS`, the default will be used, if not set otherwise. Use for all others the instance values as defined. If these environment variables are not provided or misconfigured, the collaboration service will not start up. + +Required environment variables: +* `OC_URL` +* `OC_JWT_SECRET` +* `OC_REVA_GATEWAY` +* `MICRO_REGISTRY_ADDRESS` + + +## Table of Contents + +* [Requirements](#requirements) +* [WOPI Configuration](#wopi-configuration) +* [Storing](#storing) + +## Requirements + +The collaboration service requires the target document server (ONLYOFFICE, Collabora, etc.) to be up and running. Additionally, some OpenCloud services are also required to be running in order to register the GRPC service for the `open in app` action in the webUI. The following internal and external services need to be available: + +* External document server. +* The gateway service. +* The app-registry service. + +If any of the named services above have not been started or are not reachable, the collaboration service won't start. For the binary or the docker release of OpenCloud, check with the `opencloud list` command if they have been started. If not, you must start them manually upfront before starting the collaboration service. + +## WOPI Configuration + +There are a few variables that you need to set: + +* `COLLABORATION_APP_NAME`:\ + The name of the app which is shown to the user. You can chose freely but you are limited to a single word without special characters or whitespaces. We recommend to use pascalCase like 'CollaboraOnline'. + +* `COLLABORATION_APP_PRODUCT`:\ + The product name of the connected WebOffice app, which can be one of the following:\ + `Collabora`, `OnlyOffice`, `Microsoft365` or `MicrosoftOfficeOnline`. This is used to internally control the behavior according to the different features of the used products. + +* `COLLABORATION_APP_ADDR`:\ + The URL of the collaborative editing app (onlyoffice, collabora, etc).\ + For example: `https://office.example.com`. + +* `COLLABORATION_APP_INSECURE`:\ + In case you are using a self signed certificate for the WOPI app you can tell the collaboration service to allow an insecure connection. + +* `COLLABORATION_WOPI_SRC`:\ + The external address of the collaboration service. The target app (onlyoffice, collabora, etc) will use this address to read and write files from OpenCloud.\ + For example: `https://wopi.example.com`. + +* `COLLABORATION_WOPI_SHORTTOKENS`:\ + Needs to be set if the office application like `Microsoft Office Online` complains about the URL is too long (which contains the access token) and refuses to work. If enabled, a store must be configured. + +The application can be customized further by changing the `COLLABORATION_APP_*` options to better describe the application. + +## Storing + +The `collaboration` service persists information via the configured store in `COLLABORATION_STORE`. Possible stores are: + - `memory`: Basic in-memory store. Will not survive a restart. This is not recommended for this service. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store). This is the default value. + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory.yaml new file mode 100644 index 00000000..dd10658f --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory.yaml @@ -0,0 +1,30 @@ +# Autogenerated +# Filename: eventhistory.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9270 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9274 + tls: null +grpc_client_tls: null +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" +store: + store: nats-js-kv + nodes: + - 127.0.0.1:9233 + database: eventhistory + table: "" + ttl: 336h0m0s + username: "" + password: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_configvars.mdx new file mode 100644 index 00000000..9302234a --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_configvars.mdx @@ -0,0 +1,24 @@ +Environment variables for the **eventhistory** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`EVENTHISTORY_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`EVENTHISTORY_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9270`| +|`EVENTHISTORY_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`EVENTHISTORY_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`EVENTHISTORY_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`EVENTHISTORY_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9274`| +|`OC_EVENTS_ENDPOINT`
`EVENTHISTORY_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_CLUSTER`
`EVENTHISTORY_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`EVENTHISTORY_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`EVENTHISTORY_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. Will be seen as empty if NOTIFICATIONS_EVENTS_TLS_INSECURE is provided.`|``| +|`OC_EVENTS_ENABLE_TLS`
`EVENTHISTORY_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_AUTH_USERNAME`
`EVENTHISTORY_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_AUTH_PASSWORD`
`EVENTHISTORY_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_PERSISTENT_STORE`
`EVENTHISTORY_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_NODES`
`EVENTHISTORY_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]`| +|`EVENTHISTORY_STORE_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`eventhistory`| +|`EVENTHISTORY_STORE_TABLE`| 1.0.0 |string|`The database table the store should use.`|``| +|`OC_PERSISTENT_STORE_TTL`
`EVENTHISTORY_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.`|`336h0m0s`| +|`OC_PERSISTENT_STORE_AUTH_USERNAME`
`EVENTHISTORY_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_AUTH_PASSWORD`
`EVENTHISTORY_STORE_AUTH_PASSWORD`| 1.0.0 |string|`The password to authenticate with the store. Only applies when store type 'nats-js-kv' is configured.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_readme.mdx new file mode 100755 index 00000000..133fc984 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/eventhistory_readme.mdx @@ -0,0 +1,56 @@ +--- +title: Eventhistory +date: 2026-01-15T10:35:01.390519086Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/eventhistory +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `eventhistory` consumes all events from the configured event system like NATS, stores them and allows other services to retrieve them via an event ID. + + +## Table of Contents + +* [Prerequisites](#prerequisites) +* [Consuming](#consuming) +* [Storing](#storing) +* [Retrieving](#retrieving) + +## Prerequisites + +Running the eventhistory service without an event system like NATS is not possible. + +## Consuming + +The `eventhistory` services consumes all events from the configured event system. + +## Storing + +The `eventhistory` service stores each consumed event via the configured store in `EVENTHISTORY_STORE`. Possible stores are: + - `memory`: Basic in-memory store and the default. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + +## Retrieving + +Other services can call the `eventhistory` service via a gRPC call to retrieve events. The request must contain the event ID that should be retrieved. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/extended_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/extended_configvars.mdx new file mode 100644 index 00000000..42eb93db --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/extended_configvars.mdx @@ -0,0 +1,336 @@ +# Environment variables with extended scope not included in a service + +| Name | Type | Default Value | Description | +|---|---|---|---| +`0` | | | | +`ACK_GINKGO_DEPRECATIONS` | | | | +`ACK_GINKGO_DEPRECATIONS` | | | | +`ACK_GINKGO_RC` | | | | +`ANSICON` | | | | +`ANSICON` | | | | +`ANSICON_VER` | | | | +`APP_ID` | | | | +`APP_SECRET` | | | | +`AWS_ACCESS_KEY` | | | | +`AWS_ACCESS_KEY_ID` | | | | +`AWS_CONTAINER_AUTHORIZATION_TOKEN` | | | | +`AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` | | | | +`AWS_CONTAINER_CREDENTIALS_FULL_URI` | | | | +`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` | | | | +`AWS_PROFILE` | | | | +`AWS_REGION` | | | | +`AWS_ROLE_ARN` | | | | +`AWS_ROLE_SESSION_NAME` | | | | +`AWS_SECRET_ACCESS_KEY` | | | | +`AWS_SECRET_KEY` | | | | +`AWS_SESSION_TOKEN` | | | | +`AWS_SHARED_CREDENTIALS_FILE` | | | | +`AWS_WEB_IDENTITY_TOKEN_FILE` | | | | +`BASH_COMP_DEBUG_FILE` | | | | +`BASH_COMP_DEBUG_FILE` | | | | +`CI` | | | | +`CI_SYSTEM_NAME` | | | | +`CLICOLOR` | | | | +`CLI_TEMPLATE_ERROR_DEBUG` | | | | +`CLI_TEMPLATE_ERROR_DEBUG` | | | | +`COLORTERM` | | | | +`COLORTERM` | | | | +`COMSPEC` | | | | +`CS3_GATEWAY` | | | | +`CS3_MACHINE_AUTH_API_KEY` | | | | +`ConEmuANSI` | | | | +`ConEmuANSI` | | | | +`DAYS` | | | | +`DOCKER_AUTH_CONFIG` | | | | +`DOCKER_CONFIG` | | | | +`DOCKER_HOST` | | | | +`DOCKER_HOST` | | | | +`ENV_VERIFY` | | | | +`ETCD_CLIENT_DEBUG` | | | | +`ETCD_CLIENT_DEBUG` | | | | +`EXPERIMENTAL_REGISTER_INTERVAL` | duration | 25s | The interval at which services will re-register themselves with the registry to prevent expiry. Only change on supervision of openCloud Support. | +`EXPERIMENTAL_REGISTER_TTL` | duration | 30s | The time-to-live for a service registration in the registry. Services must re-register before this time to prevent expiry. Only change on supervision of openCloud Support. | +`EXPERIMENTAL_WASM_OPT` | | | | +`EXPERIMENTAL_WASM_OPT` | | | | +`EXPERIMENTAL_WASM_OPT_ARGS` | | | | +`EXPERIMENTAL_WASM_OPT_ARGS` | | | | +`EnvOverrideAPIVersion` | | | | +`EnvOverrideCertPath` | | | | +`EnvOverrideHost` | | | | +`EnvTLSVerify` | | | | +`EnvUnixSocketDir` | | | | +`EnvUnixSocketGroup` | | | | +`EnvVarLabels` | | | | +`EnvVarType` | | | | +`FORCE_COLOR` | | | | +`FSNOTIFY_DEBUG` | | | | +`GINKGO_EDITOR_INTEGRATION` | | | | +`GINKGO_EDITOR_INTEGRATION` | | | | +`GINKGO_EDITOR_INTEGRATION` | | | | +`GINKGO_EDITOR_INTEGRATION` | | | | +`GINKGO_PARALLEL_PROTOCOL` | | | | +`GINKGO_PARALLEL_PROTOCOL` | | | | +`GINKGO_PRESERVE_CACHE` | | | | +`GINKGO_PRUNE_STACK` | | | | +`GINKGO_TIME_FORMAT` | | | | +`GINKGO_TIME_FORMAT` | | | | +`GITHUB_ACTIONS` | | | | +`GO15VENDOREXPERIMENT` | | | | +`GO15VENDOREXPERIMENT` | | | | +`GODEBUG` | | | | +`GODEBUG` | | | | +`GODEBUG` | | | | +`GOOS` | | | | +`GOPACKAGESPRINTDRIVERERRORS` | | | | +`GOPROCESS` | | | | +`GOPROTODEBUG` | | | | +`GRACEFUL` | | | | +`GRPC_GO_LOG_FORMATTER` | | | | +`GRPC_GO_LOG_SEVERITY_LEVEL` | | | | +`GRPC_GO_LOG_VERBOSITY_LEVEL` | | | | +`GRPC_TEST_ONLY_GOOGLE_C2P_RESOLVER_TRAFFIC_DIRECTOR_URI` | | | | +`HOME` | | | | +`HOME` | | | | +`HOME` | | | | +`HOME` | | | | +`HOMEDRIVE` | | | | +`HOMEDRIVE` | | | | +`HOMEDRIVE` | | | | +`HOMEPATH` | | | | +`HOMEPATH` | | | | +`HOMEPATH` | | | | +`HOSTNAME` | | | | +`HOSTNAME` | | | | +`HOSTNAME` | | | | +`HOSTNAME` | | | | +`HOSTNAME` | | | | +`HOSTNAME` | | | | +`HOSTNAME` | | | | +`HOST_ROOT` | | | | +`HOST_ROOT` | | | | +`HOST_ROOT` | | | | +`IDENTITY_ENDPOINT` | | | | +`IDENTITY_HEADER` | | | | +`JOURNAL_STREAM` | | | | +`KIDM_TEMPLATE_DEBUG` | | | | +`KOPANO_DEBUG_SERVER_REQUEST_LOG` | | | | +`KUBERNETES_SERVICE_HOST` | | | | +`KUBERNETES_SERVICE_PORT` | | | | +`LANG` | | | | +`LANG` | | | | +`LC_ALL` | | | | +`LC_CTYPE` | | | | +`LC_CTYPE` | | | | +`LDAP_BASEDN` | | | | +`LDAP_BINDDN` | | | | +`LDAP_BINDPW` | | | | +`LDAP_EMAIL_ATTRIBUTE` | | | | +`LDAP_FAMILY_NAME_ATTRIBUTE` | | | | +`LDAP_FILTER` | | | | +`LDAP_GIVEN_NAME_ATTRIBUTE` | | | | +`LDAP_LOGIN_ATTRIBUTE` | | | | +`LDAP_NAME_ATTRIBUTE` | | | | +`LDAP_SCOPE` | | | | +`LDAP_SUB_ATTRIBUTES` | | | | +`LDAP_TLS_CACERT` | | | | +`LDAP_UIDNUMBER_ATTRIBUTE` | | | | +`LDAP_URI` | | | | +`LDAP_UUID_ATTRIBUTE` | | | | +`LDAP_UUID_ATTRIBUTE_TYPE` | | | | +`LIBREGRAPH_SCOPED_URIS` | | | | +`LIBREGRAPH_URI` | | | | +`LogEnv` | | | | +`MD2MAN_DEBUG` | | | | +`MICRO_LOG_LEVEL` | | | | +`MICRO_LOG_LEVEL` | string | Error | Set the log level for the internal go micro framework. Only change on supervision of openCloud Support. | +`MICRO_LOG_LEVEL` | | | | +`MICRO_LOG_LEVEL` | | | | +`MICRO_NETWORK` | | | | +`MICRO_NETWORK_ADDRESS` | | | | +`MICRO_PROXY` | | | | +`MICRO_REGISTRY` | string | nats-js-kv | The type of registry to use. Only change on supervision of openCloud Support. | +`MICRO_REGISTRY_ADDRESS` | string | 127.0.0.1:9233 | The bind address of the internal natsjs registry. Only change on supervision of openCloud Support. | +`MICRO_REGISTRY_AUTH_PASSWORD` | string | | Optional when using nats to authenticate with the nats cluster. | +`MINIO_ACCESS_KEY` | | | | +`MINIO_ALIAS` | | | | +`MINIO_GO_TEST_BUCKET_CORS` | | | | +`MINIO_ROOT_PASSWORD` | | | | +`MINIO_ROOT_USER` | | | | +`MINIO_SECRET_KEY` | | | | +`MINT_MODE` | | | | +`MINT_NO_FULL_OBJECT` | | | | +`MINT_NO_FULL_OBJECT` | | | | +`MINT_NO_FULL_OBJECT` | | | | +`MOBY_DISABLE_PIGZ` | | | | +`MONTH` | | | | +`MSYSTEM` | | | | +`NOTIFY_ACCOUNTID` | | | | +`NOTIFY_ACCOUNTID` | | | | +`NOTIFY_BUCKET` | | | | +`NOTIFY_BUCKET` | | | | +`NOTIFY_REGION` | | | | +`NOTIFY_REGION` | | | | +`NOTIFY_RESOURCE` | | | | +`NOTIFY_RESOURCE` | | | | +`NOTIFY_SERVICE` | | | | +`NOTIFY_SERVICE` | | | | +`NO_COLOR` | | | | +`NO_COLOR` | | | | +`NO_COLOR` | | | | +`NO_COLOR` | | | | +`OC_BASE_DATA_PATH` | | | | +`OC_BASE_DATA_PATH` | string | | The base directory location used by several services and for user data. See the General Info section in the documentation for more details on defaults. Services can have, if available, an individual setting with an own environment variable. | +`OC_CONFIG_DIR` | string | | The default directory location for config files. See the General Info section in the documentation for more details on defaults. | +`OC_CONFIG_DIR` | | | | +`OC_GRPC_MAX_RECEIVED_MESSAGE_SIZE` | | | | +`OC_GRPC_MAX_RECEIVED_MESSAGE_SIZE` | integer | 10240000 | Sets the maximum message size in bytes the GRPC client can receive. | +`OPA_TELEMETRY_SERVICE_URL` | | | | +`PATH` | | | | +`PATH` | | | | +`PATH` | | | | +`PLUGIN_CLIENT_CERT` | | | | +`PLUGIN_MAX_PORT` | | | | +`PLUGIN_MIN_PORT` | | | | +`PLUGIN_PROTOCOL_VERSIONS` | | | | +`PSHOME` | | | | +`PWD` | | | | +`REVA_APPPROVIDER_IOPSECRET` | | | | +`REVA_SMTP_SENDER_PASSWORD` | | | | +`RUNEWIDTH_EASTASIAN` | | | | +`RUN_CMD_TEST` | | | | +`RUN_ON_FAIL` | | | | +`RYUK_PORT` | | | | +`SHELL` | | | | +`SSH_AUTH_SOCK` | | | | +`SSH_AUTH_SOCK` | | | | +`SSH_KNOWN_HOSTS` | | | | +`SSL_CERT_FILE` | | | | +`TERM` | | | | +`TERM` | | | | +`TERM` | | | | +`TERM` | | | | +`TERM` | | | | +`TERM` | | | | +`TERMINAL_EMULATOR` | | | | +`TERM_PROGRAM` | | | | +`TERM_PROGRAM` | | | | +`TERM_PROGRAM_VERSION` | | | | +`TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX` | | | | +`TESTCONTAINERS_RYUK_CONTAINER_PRIVILEGED` | | | | +`TESTCONTAINERS_RYUK_DISABLED` | | | | +`USER` | | | | +`USERPROFILE` | | | | +`USERPROFILE` | | | | +`USERPROFILE` | | | | +`USE_TESTCONTAINERS` | | | | +`WSL_DISTRO_NAME` | | | | +`WT_SESSION` | | | | +`XDG_CONFIG_HOME` | | | | +`XDSBootstrapFileContentEnv` | | | | +`XDSBootstrapFileNameEnv` | | | | +`YEAR` | | | | +`_registryAddressEnv` | | | | +`_registryAddressEnv` | | | | +`_registryEnv` | | | | +`_registryPasswordEnv` | | | | +`_registryRegisterIntervalEnv` | | | | +`_registryRegisterTTLEnv` | | | | +`_registryUsernameEnv` | | | | +`_serverMaxConnectionAgeEnv` | | | | +`_serverMaxConnectionAgeEnv` | | | | +`accessKey` | | | | +`accessKey` | | | | +`accessKeyEnvVar` | | | | +`activeHelpEnvVar(cmd.Root(` | | | | +`activeHelpEnvVar(cmd.Root(` | | | | +`activeHelpGlobalEnvVar` | | | | +`activeHelpGlobalEnvVar` | | | | +`ansiterm.LogEnv` | | | | +`awsConfigFileEnvVar` | | | | +`awsCredentialsFileEnvVar` | | | | +`awsDomainEnvVar` | | | | +`awsDomainEnvVar` | | | | +`awsProfileEnvVar` | | | | +`awsProfileEnvVar` | | | | +`awsRegionEnvVar` | | | | +`awsRegionEnvVar` | | | | +`awsRegionEnvVar` | | | | +`awsRegionEnvVar` | | | | +`awsRegionEnvVar` | | | | +`awsRoleArnEnvVar` | | | | +`awsRoleArnEnvVar` | | | | +`awsWebIdentityTokenFileEnvVar` | | | | +`configEnvVar(cmd.Root(` | | | | +`configEnvVar(configEnvVarGlobalPrefix, suffix` | | | | +`defaultHTTPRequestTimeoutEnv` | | | | +`ecsFullPathEnvVar` | | | | +`ecsRelativePathEnvVar` | | | | +`enableHTTPS` | | | | +`enableHTTPS` | | | | +`enableHTTPS` | | | | +`enableHTTPS` | | | | +`enableHTTPS` | | | | +`enableHTTPS` | | | | +`enableKMS` | | | | +`enableKMS` | | | | +`env` | | | | +`env` | | | | +`envAUTOMEMLIMIT_EXPERIMENT` | | | | +`envMultiplexGRPC` | | | | +`envMultiplexGRPC` | | | | +`envName` | | | | +`envObservabilityConfig` | | | | +`envObservabilityConfigFile` | | | | +`envStr` | | | | +`envVar` | | | | +`envVar` | | | | +`envVar` | | | | +`envVar` | | | | +`envVar` | | | | +`envVerify` | | | | +`f.key` | | | | +`key` | | | | +`key` | | | | +`key` | | | | +`key` | | | | +`key` | | | | +`key` | | | | +`key` | | | | +`key` | | | | +`key` | | | | +`key` | | | | +`key` | | | | +`n` | | | | +`name` | | | | +`name` | | | | +`name` | | | | +`name` | | | | +`name` | | | | +`name` | | | | +`name` | | | | +`name` | | | | +`name` | | | | +`name` | | | | +`opts.MagicCookieKey` | | | | +`parts[0]` | | | | +`prefix + envVar` | | | | +`resourceAttrKey` | | | | +`s` | | | | +`secretKey` | | | | +`secretKey` | | | | +`secretKeyEnvVar` | | | | +`securityTokenEnvVar` | | | | +`serverEndpoint` | | | | +`serverEndpoint` | | | | +`serverEndpoint` | | | | +`serverEndpoint` | | | | +`serverEndpoint` | | | | +`sessionTokenEnvVar` | | | | +`skipCERTValidation` | | | | +`strings.ToLower(key` | | | | +`strings.ToUpper(key` | | | | +`svcNameKey` | | | | +`tlsClientCertEnvVar` | | | | +`tlsClientKeyEnvVar` | | | | +`v` | | | | +`v` | | | | \ No newline at end of file diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend.yaml new file mode 100644 index 00000000..996be0f5 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend.yaml @@ -0,0 +1,166 @@ +# Autogenerated +# Filename: frontend.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9141 + token: "" + pprof: false + zpages: false +http: + addr: 127.0.0.1:9140 + protocol: tcp + prefix: "" + cors: + allow_origins: + - https://localhost:9200 + allow_methods: + - OPTIONS + - HEAD + - GET + - PUT + - POST + - PATCH + - DELETE + - MKCOL + - PROPFIND + - PROPPATCH + - MOVE + - COPY + - REPORT + - SEARCH + allow_headers: + - Origin + - Accept + - Content-Type + - Depth + - Authorization + - Ocs-Apirequest + - If-None-Match + - If-Match + - Destination + - Overwrite + - X-Request-Id + - X-Requested-With + - Tus-Resumable + - Tus-Checksum-Algorithm + - Upload-Concat + - Upload-Length + - Upload-Metadata + - Upload-Defer-Length + - Upload-Expires + - Upload-Checksum + - Upload-Offset + - X-HTTP-Method-Override + - Cache-Control + allow_credentials: false +transfer_secret: "" +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +machine_auth_api_key: "" +skip_user_groups_in_token: false +enable_favorites: false +max_quota: 0 +upload_max_chunk_size: 10000000 +upload_http_method_override: "" +default_upload_protocol: tus +enable_federated_sharing_incoming: false +enable_federated_sharing_outgoing: false +search_min_length: 3 +disable_sse: false +disable_radicale: false +default_link_permissions: 1 +public_url: https://localhost:9200 +max_concurrency: 1 +app_handler: + insecure: false + secure_view_app_addr: eu.opencloud.api.collaboration +archiver: + max_num_files: 10000 + max_size: 1073741824 + insecure: false +data_gateway: + prefix: data +ocs: + prefix: ocs + share_prefix: /Shares + home_namespace: /users/{{.Id.OpaqueId}} + additional_info_attribute: '{{.Mail}}' + stat_cache_type: memory + stat_cache_nodes: + - 127.0.0.1:9233 + stat_cache_database: cache-stat + stat_cache_table: "" + stat_cache_ttl: 5m0s + stat_cache_disable_persistence: false + stat_cache_auth_username: "" + stat_cache_auth_password: "" + enable_denials: false + list_ocm_shares: true + include_ocm_sharees: false + public_sharing_share_must_have_password: true + public_sharing_writeableshare_must_have_password: false + show_email_in_results: false +ocdav: + prefix: "" + skip_user_groups_in_token: false + webdav_namespace: /users/{{.Id.OpaqueId}} + files_namespace: /users/{{.Id.OpaqueId}} + shares_namespace: /Shares + ocm_namespace: /public + public_url: https://localhost:9200 + insecure: false + enable_http_tpc: false + gateway_request_timeout: 84300 + machine_auth_api_key: "" + allow_propfind_depth_infinity: false + name_validation: + invalid_chars: + - "\f" + - "\r" + - |2+ + + - \ + max_length: 255 +checksums: + supported_types: + - sha1 + - md5 + - adler32 + preferred_upload_type: sha1 +read_only_user_attributes: [] +ldap_server_write_enabled: true +edit_login_allowed_disabled: false +full_text_search: false +check_for_updates: true +middleware: + auth: + credentials_by_user_agent: {} +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" +grpc_client_tls: null +auto_accept_shares: true +service_account: + service_account_id: "" + service_account_secret: "" +password_policy: + min_characters: 8 + min_lowercase_characters: 1 + min_uppercase_characters: 1 + min_digits: 1 + min_special_characters: 1 + banned_passwords_list: "" +configurable_notifications: false +groupware: + enabled: false diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_configvars.mdx new file mode 100644 index 00000000..e5cf9e96 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_configvars.mdx @@ -0,0 +1,124 @@ + +2026-01-15-10-34-53 + +# Deprecation Notice + +| Deprecation Info | Deprecation Version | Removal Version | Deprecation Replacement | +|---|---|---|:---| +| The OCS API is deprecated | 1.0.0 | next-prod | | +| The OCS API is deprecated | 1.0.0 | next-prod | | +| The OCS API is deprecated | 1.0.0 | next-prod | | +| The OCS API is deprecated | 1.0.0 | next-prod | | +| FRONTEND_OCS_STAT_CACHE_STORE, the OCS API is deprecated | 1.0.0 | next-prod | | +| FRONTEND_OCS_STAT_CACHE_STORE_NODES, the OCS API is deprecated | 1.0.0 | next-prod | | +| The OCS API is deprecated | 1.0.0 | next-prod | | +| FRONTEND_OCS_STAT_CACHE_TTL, the OCS API is deprecated | 1.0.0 | next-prod | | +| FRONTEND_OCS_STAT_CACHE_DISABLE_PERSISTENCE, the OCS API is deprecated | 1.0.0 | next-prod | | +| FRONTEND_OCS_STAT_CACHE_AUTH_USERNAME, the OCS API is deprecated | 1.0.0 | next-prod | | +| FRONTEND_OCS_STAT_CACHE_AUTH_PASSWORD, the OCS API is deprecated | 1.0.0 | next-prod | | +| The OCS API is deprecated | 1.0.0 | next-prod | | +| FRONTEND_OCS_LIST_OCM_SHARES, the OCS API is deprecated | 1.0.0 | next-prod | | +| FRONTEND_OCS_INCLUDE_OCM_SHAREES, the OCS API is deprecated | 1.0.0 | next-prod | | +| FRONTEND_OCS_PUBLIC_SHARE_MUST_HAVE_PASSWORD, the OCS API is deprecated | 1.0.0 | next-prod | | +| FRONTEND_OCS_PUBLIC_WRITABLE_SHARE_MUST_HAVE_PASSWORD, the OCS API is deprecated | 1.0.0 | next-prod | | +Environment variables for the **frontend** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`FRONTEND_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`FRONTEND_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9141`| +|`FRONTEND_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`FRONTEND_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`FRONTEND_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`FRONTEND_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9140`| +|`FRONTEND_HTTP_PROTOCOL`| 1.0.0 |string|`The transport protocol of the HTTP service.`|`tcp`| +|`FRONTEND_HTTP_PREFIX`| 1.0.0 |string|`The Path prefix where the frontend can be accessed (defaults to /).`|``| +|`OC_CORS_ALLOW_ORIGINS`
`FRONTEND_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.`|`[https://localhost:9200]`| +|`OC_CORS_ALLOW_METHODS`
`FRONTEND_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.`|`[OPTIONS HEAD GET PUT POST PATCH DELETE MKCOL PROPFIND PROPPATCH MOVE COPY REPORT SEARCH]`| +|`OC_CORS_ALLOW_HEADERS`
`FRONTEND_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.`|`[Origin Accept Content-Type Depth Authorization Ocs-Apirequest If-None-Match If-Match Destination Overwrite X-Request-Id X-Requested-With Tus-Resumable Tus-Checksum-Algorithm Upload-Concat Upload-Length Upload-Metadata Upload-Defer-Length Upload-Expires Upload-Checksum Upload-Offset X-HTTP-Method-Override Cache-Control]`| +|`OC_CORS_ALLOW_CREDENTIALS`
`FRONTEND_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.`|`false`| +|`OC_TRANSFER_SECRET`| 1.0.0 |string|`Transfer secret for signing file up- and download requests.`|``| +|`OC_JWT_SECRET`
`FRONTEND_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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_MACHINE_AUTH_API_KEY`
`FRONTEND_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.`|``| +|`FRONTEND_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the loading of user's group memberships from the reva access token.`|`false`| +|`FRONTEND_ENABLE_FAVORITES`| 1.0.0 |bool|`Enables the support for favorites in the clients.`|`false`| +|`OC_SPACES_MAX_QUOTA`
`FRONTEND_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`| +|`FRONTEND_UPLOAD_MAX_CHUNK_SIZE`| 1.0.0 |int|`Sets the max chunk sizes in bytes for uploads via the clients.`|`10000000`| +|`FRONTEND_UPLOAD_HTTP_METHOD_OVERRIDE`| 1.0.0 |string|`Advise TUS to replace PATCH requests by POST requests.`|``| +|`FRONTEND_DEFAULT_UPLOAD_PROTOCOL`| 1.0.0 |string|`The default upload protocol to use in clients. Currently only 'tus' is available. See the developer API documentation for more details about TUS.`|`tus`| +|`OC_ENABLE_OCM`
`FRONTEND_ENABLE_FEDERATED_SHARING_INCOMING`| 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`
`FRONTEND_ENABLE_FEDERATED_SHARING_OUTGOING`| 1.0.0 |bool|`Changing this value is NOT supported. Enables support for outgoing federated sharing for clients. The backend behaviour is not changed.`|`false`| +|`FRONTEND_SEARCH_MIN_LENGTH`| 1.0.0 |int|`Minimum number of characters to enter before a client should start a search for Share receivers. This setting can be used to customize the user experience if e.g too many results are displayed.`|`3`| +|`OC_DISABLE_SSE`
`FRONTEND_DISABLE_SSE`| 1.0.0 |bool|`When set to true, clients are informed that the Server-Sent Events endpoint is not accessible.`|`false`| +|`FRONTEND_DISABLE_RADICALE`| 4.0.0 |bool|`When set to true, clients are informed that the Radicale (CalDAV/CardDAV) is not accessible.`|`false`| +|`FRONTEND_DEFAULT_LINK_PERMISSIONS`| 1.0.0 |int|`Defines the default permissions a link is being created with. Possible values are 0 (= internal link, for instance members only) and 1 (= public link with viewer permissions). Defaults to 1.`|`1`| +|`OC_URL`
`FRONTEND_PUBLIC_URL`| 1.0.0 |string|`The public facing URL of the OpenCloud frontend.`|`https://localhost:9200`| +|`OC_MAX_CONCURRENCY`
`FRONTEND_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_INSECURE`
`FRONTEND_APP_HANDLER_INSECURE`| 1.0.0 |bool|`Allow insecure connections to the frontend.`|`false`| +|`FRONTEND_APP_HANDLER_SECURE_VIEW_APP_ADDR`| 1.0.0 |string|`Service name or address of the app provider to use for secure view. Should match the service name or address of the registered CS3 app provider.`|`eu.opencloud.api.collaboration`| +|`FRONTEND_ARCHIVER_MAX_NUM_FILES`| 1.0.0 |int64|`Max number of files that can be packed into an archive.`|`10000`| +|`FRONTEND_ARCHIVER_MAX_SIZE`| 1.0.0 |int64|`Max size in bytes of the zip archive the archiver can create.`|`1073741824`| +|`OC_INSECURE`
`FRONTEND_ARCHIVER_INSECURE`| 1.0.0 |bool|`Allow insecure connections to the archiver.`|`false`| +|`FRONTEND_DATA_GATEWAY_PREFIX`| 1.0.0 |string|`Path prefix for the data gateway.`|`data`| +|`FRONTEND_OCS_PREFIX`| 1.0.0 |string|`URL path prefix for the OCS service. Note that the string must not start with '/'.`|`ocs`| +|`FRONTEND_OCS_SHARE_PREFIX`| 1.0.0 |string|`Path prefix for shares as part of a CS3 resource. Note that the path must start with '/'.`|`/Shares`| +|`FRONTEND_OCS_PERSONAL_NAMESPACE`| 1.0.0 |string|`Home namespace identifier.`|`/users/{{.Id.OpaqueId}}`| +|`FRONTEND_OCS_ADDITIONAL_INFO_ATTRIBUTE`| 1.0.0 |string|`Additional information attribute for the user like {{.Mail}}.`|`{{.Mail}}`| +|`OC_CACHE_STORE`
`FRONTEND_OCS_STAT_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`
`FRONTEND_OCS_STAT_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_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`cache-stat`| +|`FRONTEND_OCS_STAT_CACHE_TABLE`| 1.0.0 |string|`The database table the store should use.`|``| +|`OC_CACHE_TTL`
`FRONTEND_OCS_STAT_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_DISABLE_PERSISTENCE`
`FRONTEND_OCS_STAT_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_USERNAME`
`FRONTEND_OCS_STAT_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_AUTH_PASSWORD`
`FRONTEND_OCS_STAT_CACHE_AUTH_PASSWORD`| 1.0.0 |string|`The password to use for authentication. Only applies when using the 'nats-js-kv' store type.`|``| +|`FRONTEND_OCS_ENABLE_DENIALS`| 1.0.0 |bool|`EXPERIMENTAL: enable the feature to deny access on folders.`|`false`| +|`OC_ENABLE_OCM`
`FRONTEND_OCS_LIST_OCM_SHARES`| 1.0.0 |bool|`Include OCM shares when listing shares. See the OCM service documentation for more details.`|`true`| +|`OC_ENABLE_OCM`
`FRONTEND_OCS_INCLUDE_OCM_SHAREES`| 1.0.0 |bool|`Include OCM sharees when listing sharees.`|`false`| +|`OC_SHARING_PUBLIC_SHARE_MUST_HAVE_PASSWORD`
`FRONTEND_OCS_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`
`FRONTEND_OCS_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`| +|`OCDAV_HTTP_PREFIX`
`FRONTENT_OCDAV_HTTP_PREFIX`| 1.0.0 |string|`A URL path prefix for the handler.`|``| +|`OCDAV_SKIP_USER_GROUPS_IN_TOKEN`
`FRONTENT_OCDAV_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the loading of user's group memberships from the reva access token.`|`false`| +|`OCDAV_WEBDAV_NAMESPACE`
`FRONTENT_OCDAV_WEBDAV_NAMESPACE`| 1.0.0 |string|`Jail requests to /dav/webdav into this CS3 namespace. Supports template layouting with CS3 User properties.`|`/users/{{.Id.OpaqueId}}`| +|`OCDAV_FILES_NAMESPACE`
`FRONTENT_OCDAV_FILES_NAMESPACE`| 1.0.0 |string|`Jail requests to /dav/files/{username} into this CS3 namespace. Supports template layouting with CS3 User properties.`|`/users/{{.Id.OpaqueId}}`| +|`OCDAV_SHARES_NAMESPACE`
`FRONTENT_OCDAV_SHARES_NAMESPACE`| 1.0.0 |string|`The human readable path for the share jail. Relative to a users personal space root. Upcased intentionally.`|`/Shares`| +|`OCDAV_OCM_NAMESPACE`
`FRONTENT_OCDAV_OCM_NAMESPACE`| 1.0.0 |string|`The human readable path prefix for the ocm shares.`|`/public`| +|`OC_URL`
`OCDAV_PUBLIC_URL`
`FRONTENT_OCDAV_PUBLIC_URL`| 1.0.0 |string|`URL where OpenCloud is reachable for users.`|`https://localhost:9200`| +|`OC_INSECURE`
`OCDAV_INSECURE`
`FRONTENT_OCDAV_INSECURE`| 1.0.0 |bool|`Allow insecure connections to the GATEWAY service.`|`false`| +|`OCDAV_ENABLE_HTTP_TPC`
`FRONTENT_OCDAV_ENABLE_HTTP_TPC`| next |bool|`Enable HTTP / WebDAV Third-Party-Copy support.`|`false`| +|`OCDAV_GATEWAY_REQUEST_TIME`
`FRONTENT_OUTOCDAV_GATEWAY_REQUEST_TIMEOUT`| 1.0.0 |int64|`Request timeout in seconds for requests from the oCDAV service to the GATEWAY service.`|`84300`| +|`OC_MACHINE_AUTH_API_KEY`
`OCDAV_MACHINE_AUTH_API_KEY`
`FRONTENT_OCDAV_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.`|``| +|`OCDAV_ALLOW_PROPFIND_DEPTH_INFINITY`
`FRONTENT_OCDAV_ALLOW_PROPFIND_DEPTH_INFINITY`| 1.0.0 |bool|`Allow the use of depth infinity in PROPFINDS. When enabled, a propfind will traverse through all subfolders. If many subfolders are expected, depth infinity can cause heavy server load and/or delayed response times.`|`false`| +|`OCDAV_NAME_VALIDATION_INVALID_CHARS`
`FRONTENT_OCDAV_NAME_VALIDATION_INVALID_CHARS`| next |[]string|`List of characters that are not allowed in file or folder names.`|`[ + \]`| +|`OCDAV_NAME_VALIDATION_MAX_LENGTH`
`FRONTENT_OCDAV_NAME_VALIDATION_MAX_LENGTH`| next |int|`Max lenght og file or folder names.`|`255`| +|`FRONTEND_CHECKSUMS_SUPPORTED_TYPES`| 1.0.0 |[]string|`A list of checksum types that indicate to clients which hashes the server can use to verify upload integrity. Supported types are 'sha1', 'md5' and 'adler32'. See the Environment Variable Types description for more details.`|`[sha1 md5 adler32]`| +|`FRONTEND_CHECKSUMS_PREFERRED_UPLOAD_TYPE`| 1.0.0 |string|`The supported checksum type for uploads that indicates to clients supporting multiple hash algorithms which one is preferred by the server. Must be one out of the defined list of SUPPORTED_TYPES.`|`sha1`| +|`FRONTEND_READONLY_USER_ATTRIBUTES`| 1.0.0 |[]string|`A list of user attributes to indicate as read-only. Supported values: 'user.onPremisesSamAccountName' (username), 'user.displayName', 'user.mail', 'user.passwordProfile' (password), 'user.appRoleAssignments' (role), 'user.memberOf' (groups), 'user.accountEnabled' (login allowed), 'drive.quota' (quota). See the Environment Variable Types description for more details.`|`[]`| +|`OC_LDAP_SERVER_WRITE_ENABLED`
`FRONTEND_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`| +|`FRONTEND_EDIT_LOGIN_ALLOWED_DISABLED`| 3.4.0 |bool|`Used to set if login is allowed/forbidden for for User.`|`false`| +|`FRONTEND_FULL_TEXT_SEARCH_ENABLED`| 1.0.0 |bool|`Set to true to signal the web client that full-text search is enabled.`|`false`| +|`FRONTEND_CHECK_FOR_UPDATES`| 3.6.0 |bool|`Enable automatic checking for updates. Defaults to true.`|`true`| +|`OC_EVENTS_ENDPOINT`
`FRONTEND_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_CLUSTER`
`FRONTEND_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`FRONTEND_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`FRONTEND_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`OCS_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided NOTIFICATIONS_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`FRONTEND_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_AUTH_USERNAME`
`FRONTEND_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_AUTH_PASSWORD`
`FRONTEND_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.`|``| +|`FRONTEND_AUTO_ACCEPT_SHARES`| 1.0.0 |bool|`Defines if shares should be auto accepted by default. Users can change this setting individually in their profile.`|`true`| +|`OC_SERVICE_ACCOUNT_ID`
`FRONTEND_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`
`FRONTEND_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| +|`OC_PASSWORD_POLICY_DISABLED`
`FRONTEND_PASSWORD_POLICY_DISABLED`| 1.0.0 |bool|`Disable the password policy. Defaults to false if not set.`|`false`| +|`OC_PASSWORD_POLICY_MIN_CHARACTERS`
`FRONTEND_PASSWORD_POLICY_MIN_CHARACTERS`| 1.0.0 |int|`Define the minimum password length. Defaults to 8 if not set.`|`8`| +|`OC_PASSWORD_POLICY_MIN_LOWERCASE_CHARACTERS`
`FRONTEND_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_UPPERCASE_CHARACTERS`
`FRONTEND_PASSWORD_POLICY_MIN_UPPERCASE_CHARACTERS`| 1.0.0 |int|`Define the minimum number of lowercase letters. Defaults to 1 if not set.`|`1`| +|`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_GROUPWARE_ENABLED`| 3.7.0 |bool|`Enable groupware features. Defaults to false.`|`false`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_deprecation.mdx new file mode 100644 index 00000000..d7c2fb71 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_deprecation.mdx @@ -0,0 +1,4 @@ + +:::danger +frontend has deprecated environment variables. Please refer to the table below for more information. +::: \ No newline at end of file diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_readme.mdx new file mode 100755 index 00000000..2261e88b --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/frontend_readme.mdx @@ -0,0 +1,176 @@ +--- +title: Frontend +date: 2026-01-15T10:35:01.390625926Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/frontend +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The frontend service translates various OpenCloud related HTTP APIs to CS3 requests. + + +## Table of Contents + +* [Endpoints Overview](#endpoints-overview) + * [appprovider](#appprovider) + * [archiver](#archiver) + * [datagateway](#datagateway) + * [ocs](#ocs) + * [Event Handler](#event-handler) + * [Sharing](#sharing) +* [Scalability](#scalability) +* [Define Read-Only Attributes](#define-read-only-attributes) +* [Caching](#caching) + * [Auto-Accept Shares](#auto-accept-shares) +* [Passwords](#passwords) + * [The Password Policy](#the-password-policy) + * [The Password Policy Capability](#the-password-policy-capability) + * [Password Enforcement for all Public Links](#password-enforcement-for-all-public-links) + * [Password Enforcement for Writeable Public Links](#password-enforcement-for-writeable-public-links) + +## Endpoints Overview + +Currently, the frontend service handles requests for three functionalities, which are `appprovider`, `archiver`, `datagateway` and `ocs`. + +### appprovider + +The appprovider endpoint, by default `/app`, forwards HTTP requests to the CS3 [App Registry API](https://cs3org.github.io/cs3apis/#cs3.app.registry.v1beta1.RegistryAPI) + +### archiver + +The archiver endpoint, by default `/archiver`, implements zip and tar download for collections of files. It will internally use the CS3 API to initiate downloads and then stream the individual files as part of a compressed file. + +### datagateway + +The datagateway endpoint, by default `/data`, forwards file up- and download requests to the correct CS3 data provider. OpenCloud starts a dataprovider as part of the storage-* services. The routing happens based on the JWT that was created by a storage provider in response to an `InitiateFileDownload` or `InitiateFileUpload` request. + +### ocs + +The ocs endpoint, by default `/ocs`, implements the Open Collaboration Services API by translating it into CS3 API requests. It can handle users, groups, capabilities and also implements the files sharing functionality on top of CS3. The `/ocs/v[12].php/cloud/user/signing-key` is currently handled by the dedicated [ocs](https://github.com/opencloud-eu/opencloud/tree/main/services/ocs) service. + +#### Event Handler + +The `frontend` service contains an eventhandler for handling `ocs` related events. As of now, it only listens to the `ShareCreated` event. + +### Sharing + +Aggregating share information is one of the most time consuming operations in OpenCloud. The service fetches a list of either received or created shares and has to stat every resource individually. While stats are fast, the default behavior scales linearly with the number of shares. + +To save network trips the sharing implementation can cache the stat requests with an in memory cache or in Redis. It will shorten the response time by the network round-trip overhead at the cost of the API only eventually being updated. + +Setting `FRONTEND_OCS_RESOURCE_INFO_CACHE_TTL=60` (deprecated) would cache the stat info for 60 seconds. Increasing this value makes sense for large deployments with thousands of active users that keep the cache up to date. Low frequency usage scenarios should not expect a noticeable improvement. + +## Scalability + +While the frontend service does not persist any data, it does cache information about files and filesystem (`Stat()`) responses and user information. Therefore, multiple instances of this service can be spawned in a bigger deployment like when using container orchestration with Kubernetes, when configuring `FRONTEND_OCS_RESOURCE_INFO_CACHE_STORE` (deprecated) and the related config options. + +## Define Read-Only Attributes + +A lot of user management is made via the standardized libregraph API. Depending on how the system is configured, there might be some user attributes that an OpenCloud instance admin can't change because of properties coming from an external LDAP server, or similar. This can be the case when the OpenCloud admin is not the LDAP admin. To ease life for admins, there are hints as capabilites telling the frontend which attributes are read-only to enable a different optical representation like being grayed out. To configure these hints, use the environment variable `FRONTEND_READONLY_USER_ATTRIBUTES`, which takes a comma separated list of attributes, see the envvar for supported values. + +You can find more details regarding available attributes at the [libre-graph-api openapi-spec](https://github.com/opencloud-eu/libre-graph-api/blob/main/api/openapi-spec/v1.0.yaml) and on [docs.opencloud.eu](https://docs.opencloud.eu/swagger/libre-graph-api/). + +## Caching + +The `frontend` service can use a configured store via `FRONTEND_OCS_STAT_CACHE_STORE` (deprecated). Possible stores are: + - `memory`: Basic in-memory store and the default. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + +### Auto-Accept Shares + +When setting the `FRONTEND_AUTO_ACCEPT_SHARES` to `true`, all incoming shares will be accepted automatically. Users can overwrite this setting individually in their profile. + +## Passwords + +### The Password Policy + +Note that the password policy currently impacts only **public link password validation**. + +In OpenCloud, the password policy is always enabled because the max-length restriction is always applying and should be taken into account by the clients. + +With the password policy, mandatory criteria for the password can be defined via the environment variables listed below. + +Generally, a password can contain any UTF-8 characters, however some characters are regarded as special since they are not used in ordinary texts. Which characters should be treated as special is defined by "The OWASP® Foundation" [password-special-characters](https://owasp.org/www-community/password-special-characters) (between double quotes): ```" !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~"``` + +The validation against the banned passwords list can be configured via a text file with words separated by new lines. If a user tries to set a password listed in the banned passwords list, the password can not be used (is invalid) even if the other mandatory criteria are passed. The admin can define the path of the banned passwords list file. If the file doesn't exist in a location, OpenCloud tries to load a file from the `OC_CONFIG_DIR/OC_PASSWORD_POLICY_BANNED_PASSWORDS_LIST`. An option will be enabled when the file has been loaded successfully. + +Following environment variables can be set to define the password policy behaviour: + +- `OC_PASSWORD_POLICY_DISABLED` +Disable the password policy +- `OC_PASSWORD_POLICY_MIN_CHARACTERS` +Define the minimum password length. +- `OC_PASSWORD_POLICY_MIN_LOWERCASE_CHARACTERS` +Define the minimum number of uppercase letters. +- `OC_PASSWORD_POLICY_MIN_UPPERCASE_CHARACTERS` +Define the minimum number of lowercase letters. +- `OC_PASSWORD_POLICY_MIN_DIGITS` +Define the minimum number of digits. +- `OC_PASSWORD_POLICY_MIN_SPECIAL_CHARACTERS` +Define the minimum number of special characters. +- `OC_PASSWORD_POLICY_BANNED_PASSWORDS_LIST` +Path to the 'banned passwords list' file. + +These variables are global OpenCloud variables because they are used not only in the frontend service, but also in the sharing service. + +Note that a password can have a maximum length of **72 bytes**. Depending on the alphabet used, a character is encoded by 1 to 4 bytes, defining the maximum length of a password indirectly. While US-ASCII will only need one byte, Latin alphabets and also Greek or Cyrillic ones need two bytes. Three bytes are needed for characters in Chinese, Japanese and Korean etc. + +### The Password Policy Capability + +The capabilities endpoint (e.g. https://cloud.opencloud.test/ocs/v1.php/cloud/capabilities?format=json) gives you following capabilities which are relevant for the password policy: + +```json +{ + "ocs": { + "data": { + "capabilities": { + "password_policy": { + "min_characters": 10, + "max_characters": 72, + "min_lowercase_characters": 1, + "min_uppercase_characters": 2, + "min_digits": 1, + "min_special_characters": 1 + } + } + } + } +} +``` + +### Password Enforcement for all Public Links + +For public accessible shares, independent if read only or writable, a password is enforced. To change this requirement, set the following environment variable to `false`: + +`OC_SHARING_PUBLIC_SHARE_MUST_HAVE_PASSWORD` + +### Password Enforcement for Writeable Public Links + +For public accessible writable shares, a password can be enforced. To change the current setting, set the following environment variable to `true`: + +`OC_SHARING_PUBLIC_WRITEABLE_SHARE_MUST_HAVE_PASSWORD` + +Note that changing this environment variable only makes sense if\ +`OC_SHARING_PUBLIC_SHARE_MUST_HAVE_PASSWORD`\ +is set to `false`. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway.yaml new file mode 100644 index 00000000..410ed3ea --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway.yaml @@ -0,0 +1,63 @@ +# Autogenerated +# Filename: gateway.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9143 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9142 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +skip_user_groups_in_token: false +commit_share_to_storage_grant: true +share_folder_name: Shares +disable_home_creation_on_login: true +transfer_secret: "" +transfer_expires: 86400 +cache: + provider_cache_store: noop + provider_cache_nodes: + - 127.0.0.1:9233 + provider_cache_database: cache-providers + provider_cache_ttl: 5m0s + provider_cache_disable_persistence: false + provider_cache_auth_username: "" + provider_cache_auth_password: "" + create_home_cache_store: memory + create_home_cache_nodes: + - 127.0.0.1:9233 + create_home_cache_database: cache-createhome + create_home_cache_ttl: 5m0s + create_home_cache_disable_persistence: false + create_home_cache_auth_username: "" + create_home_cache_auth_password: "" +frontend_public_url: https://localhost:9200 +users_endpoint: eu.opencloud.api.users +groups_endpoint: eu.opencloud.api.groups +permissions_endpoint: eu.opencloud.api.settings +sharing_endpoint: eu.opencloud.api.sharing +auth_app_endpoint: eu.opencloud.api.auth-app +auth_basic_endpoint: eu.opencloud.api.auth-basic +auth_bearer_endpoint: "" +auth_machine_endpoint: eu.opencloud.api.auth-machine +auth_service_endpoint: eu.opencloud.api.auth-service +storage_public_link_endpoint: eu.opencloud.api.storage-publiclink +storage_users_endpoint: eu.opencloud.api.storage-users +storage_shares_endpoint: eu.opencloud.api.storage-shares +app_registry_endpoint: eu.opencloud.api.app-registry +ocm_endpoint: eu.opencloud.api.ocm +storage_registry: + driver: spaces + rules: [] + json: "" + storage_users_mount_id: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_configvars.mdx new file mode 100644 index 00000000..b9b218f3 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_configvars.mdx @@ -0,0 +1,54 @@ +Environment variables for the **gateway** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`GATEWAY_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`GATEWAY_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9143`| +|`GATEWAY_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`GATEWAY_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`GATEWAY_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`OC_GATEWAY_GRPC_ADDR`
`GATEWAY_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9142`| +|`OC_GRPC_PROTOCOL`
`GATEWAY_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`OC_JWT_SECRET`
`GATEWAY_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`GATEWAY_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the loading of user's group memberships from the reva access token.`|`false`| +|`GATEWAY_COMMIT_SHARE_TO_STORAGE_GRANT`| 1.0.0 |bool|`Commit shares to storage grants. This grants access to shared resources for the share receiver directly on the storage.`|`true`| +|`GATEWAY_SHARE_FOLDER_NAME`| 1.0.0 |string|`Name of the share folder in users' home space.`|`Shares`| +|`GATEWAY_DISABLE_HOME_CREATION_ON_LOGIN`| 1.0.0 |bool|`Disable creation of the home space on login.`|`true`| +|`OC_TRANSFER_SECRET`| 1.0.0 |string|`The storage transfer secret.`|``| +|`GATEWAY_TRANSFER_EXPIRES`| 1.0.0 |int|`Expiry for the gateway tokens.`|`86400`| +|`OC_CACHE_STORE`
`GATEWAY_PROVIDER_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.`|`noop`| +|`OC_CACHE_STORE_NODES`
`GATEWAY_PROVIDER_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_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`cache-providers`| +|`OC_CACHE_TTL`
`GATEWAY_PROVIDER_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_DISABLE_PERSISTENCE`
`GATEWAY_PROVIDER_CACHE_DISABLE_PERSISTENCE`| 1.0.0 |bool|`Disables persistence of the provider cache. Only applies when store type 'nats-js-kv' is configured. Defaults to false.`|`false`| +|`OC_CACHE_AUTH_USERNAME`
`GATEWAY_PROVIDER_CACHE_AUTH_USERNAME`| 1.0.0 |string|`The username to use for authentication. Only applies when store type 'nats-js-kv' is configured.`|``| +|`OC_CACHE_AUTH_PASSWORD`
`GATEWAY_PROVIDER_CACHE_AUTH_PASSWORD`| 1.0.0 |string|`The password to use for authentication. Only applies when store type 'nats-js-kv' is configured.`|``| +|`OC_CACHE_STORE`
`GATEWAY_CREATE_HOME_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`
`GATEWAY_CREATE_HOME_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_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`cache-createhome`| +|`OC_CACHE_TTL`
`GATEWAY_CREATE_HOME_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_DISABLE_PERSISTENCE`
`GATEWAY_CREATE_HOME_CACHE_DISABLE_PERSISTENCE`| 1.0.0 |bool|`Disables persistence of the create home cache. Only applies when store type 'nats-js-kv' is configured. Defaults to false.`|`false`| +|`OC_CACHE_AUTH_USERNAME`
`GATEWAY_CREATE_HOME_CACHE_AUTH_USERNAME`| 1.0.0 |string|`The username to use for authentication. Only applies when store type 'nats-js-kv' is configured.`|``| +|`OC_CACHE_AUTH_PASSWORD`
`GATEWAY_CREATE_HOME_CACHE_AUTH_PASSWORD`| 1.0.0 |string|`The password to use for authentication. Only applies when store type 'nats-js-kv' is configured.`|``| +|`OC_URL`
`GATEWAY_FRONTEND_PUBLIC_URL`| 1.0.0 |string|`The public facing URL of the OpenCloud frontend.`|`https://localhost:9200`| +|`GATEWAY_USERS_ENDPOINT`| 1.0.0 |string|`The endpoint of the users service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.users`| +|`GATEWAY_GROUPS_ENDPOINT`| 1.0.0 |string|`The endpoint of the groups service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.groups`| +|`GATEWAY_PERMISSIONS_ENDPOINT`| 1.0.0 |string|`The endpoint of the permissions service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.settings`| +|`GATEWAY_SHARING_ENDPOINT`| 1.0.0 |string|`The endpoint of the shares service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.sharing`| +|`GATEWAY_AUTH_APP_ENDPOINT`| 1.0.0 |string|`The endpoint of the auth-app service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.auth-app`| +|`GATEWAY_AUTH_BASIC_ENDPOINT`| 1.0.0 |string|`The endpoint of the auth-basic service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.auth-basic`| +|`GATEWAY_AUTH_BEARER_ENDPOINT`| 1.0.0 |string|`The endpoint of the auth-bearer service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|``| +|`GATEWAY_AUTH_MACHINE_ENDPOINT`| 1.0.0 |string|`The endpoint of the auth-machine service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.auth-machine`| +|`GATEWAY_AUTH_SERVICE_ENDPOINT`| 1.0.0 |string|`The endpoint of the auth-service service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.auth-service`| +|`GATEWAY_STORAGE_PUBLIC_LINK_ENDPOINT`| 1.0.0 |string|`The endpoint of the storage-publiclink service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.storage-publiclink`| +|`GATEWAY_STORAGE_USERS_ENDPOINT`| 1.0.0 |string|`The endpoint of the storage-users service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.storage-users`| +|`GATEWAY_STORAGE_SHARES_ENDPOINT`| 1.0.0 |string|`The endpoint of the storage-shares service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.storage-shares`| +|`GATEWAY_APP_REGISTRY_ENDPOINT`| 1.0.0 |string|`The endpoint of the app-registry service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.app-registry`| +|`GATEWAY_OCM_ENDPOINT`| 1.0.0 |string|`The endpoint of the ocm service. Can take a service name or a gRPC URI with the dns, kubernetes or unix protocol.`|`eu.opencloud.api.ocm`| +|`GATEWAY_STORAGE_REGISTRY_DRIVER`| 1.0.0 |string|`The driver name of the storage registry to use.`|`spaces`| +|`GATEWAY_STORAGE_REGISTRY_RULES`| 1.0.0 |[]string|`The rules for the storage registry. See the Environment Variable Types description for more details.`|`[]`| +|`GATEWAY_STORAGE_REGISTRY_CONFIG_JSON`| 1.0.0 |string|`Additional configuration for the storage registry in json format.`|``| +|`GATEWAY_STORAGE_USERS_MOUNT_ID`| 1.0.0 |string|`Mount ID of this storage. Admins can set the ID for the storage in this config option manually which is then used to reference the storage. Any reasonable long string is possible, preferably this would be an UUIDv4 format.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_readme.mdx new file mode 100755 index 00000000..38a13929 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/gateway_readme.mdx @@ -0,0 +1,196 @@ +--- +title: Gateway +date: 2026-01-15T10:35:01.390833685Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/gateway +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The gateway service is responsible for passing requests to the storage providers. Other services never talk to the storage providers directly but will always send their requests via the `gateway` service. + + +## Table of Contents + +* [Caching](#caching) +* [Service Endpoints](#service-endpoints) +* [Storage Registry](#storage-registry) + +## Caching + +The gateway service is using caching as it is highly frequented with the same requests. As of now it uses two different caches: + - the `provider cache` is caching requests to list or get storage providers. + - the `create home cache` is caching requests to create personal spaces (as they only need to be executed once). + +Both caches can be configured via the `OC_CACHE_*` envvars (or `GATEWAY_PROVIDER_CACHE_*` and `GATEWAY_CREATE_HOME_CACHE_*` respectively). + +Use `OC_CACHE_STORE` (`GATEWAY_PROVIDER_CACHE_STORE`, `GATEWAY_CREATE_HOME_CACHE_STORE`) to define the type of cache to use: + - `memory`: Basic in-memory store and the default. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + +## Service Endpoints + +**IMPORTANT**\ +This functionality is currently highly experimental and intended for testing only! There are known bugs that need to be sorted out like not removing sockets when a service ends. + +The gateway acts as a proxy for other CS3 services. As such it has to forward requests to a lot of services and needs to establish connections by looking up the IP address using the service registry. Instead of using the service registry each endpoint can also be configured to use the grpc `dns://` or `kubernetes://` URLs, which might be useful when running in kubernetes. + +For a local single node deployment you might want to use `unix:` sockets as shown below. Using unix sockets will reduce the amount of service lookups and omit the TCP stack. For now, this is experimental and the services do not delete the socket on shutdown. PRs welcome. + +The scheme for this setup is the following. Note that there is, except storage, always a service and a gateway envvar triple: + +| **envvar** | **default** | **alternative** | +|------|------|------| +| OC_GRPC_PROTOCOL or
``_GRPC_PROTOCOL | tcp | unix | +| ``_GRPC_ADDR | 127.0.0.1:`` | /var/run/opencloud/``.sock | +| GATEWAY_``_ENDPOINT | eu.opencloud.api.`` | unix:/var/run/opencloud/``.sock
dns: ...
kubernetes: ... | + +```console +USERS_GRPC_PROTOCOL=unix" +USERS_GRPC_ADDR=/var/run/opencloud/users.sock" +GATEWAY_USERS_ENDPOINT=unix:/var/run/opencloud/users.sock" + +GROUPS_GRPC_PROTOCOL=unix" +GROUPS_GRPC_ADDR=/var/run/opencloud/groups.sock" +GATEWAY_GROUPS_ENDPOINT=unix:/var/run/opencloud/groups.sock" + +AUTH_APP_GRPC_PROTOCOL=unix" +AUTH_APP_GRPC_ADDR=/var/run/opencloud/auth-app.sock" +GATEWAY_AUTH_APP_ENDPOINT=unix:/var/run/opencloud/auth-app.sock" + +AUTH_BASIC_GRPC_PROTOCOL=unix" +AUTH_BASIC_GRPC_ADDR=/var/run/opencloud/auth-basic.sock" +GATEWAY_AUTH_BASIC_ENDPOINT=unix:/var/run/opencloud/auth-basic.sock" + +AUTH_MACHINE_GRPC_PROTOCOL=unix" +AUTH_MACHINE_GRPC_ADDR=/var/run/opencloud/auth-machine.sock" +GATEWAY_AUTH_MACHINE_ENDPOINT=unix:/var/run/opencloud/auth-machine.sock" + +AUTH_SERVICE_GRPC_PROTOCOL=unix" +AUTH_SERVICE_GRPC_ADDR=/var/run/opencloud/auth-service.sock" +GATEWAY_AUTH_SERVICE_ENDPOINT=unix:/var/run/opencloud/auth-service.sock" + +STORAGE_PUBLIC_LINK_GRPC_PROTOCOL=unix" +STORAGE_PUBLIC_LINK_GRPC_ADDR=/var/run/opencloud/storage-public-link.sock" +GATEWAY_STORAGE_PUBLIC_LINK_ENDPOINT=unix:/var/run/opencloud/storage-public-link.sock" + +STORAGE_USERS_GRPC_PROTOCOL=unix" +STORAGE_USERS_GRPC_ADDR=/var/run/opencloud/storage-users.sock" +GATEWAY_STORAGE_USERS_ENDPOINT=unix:/var/run/opencloud/storage-users.sock" +// graph sometimes bypasses the gateway so we need to configure the socket here as wel +GRAPH_SPACES_STORAGE_USERS_ADDRESS=unix:/var/run/opencloud/storage-users.sock" + +STORAGE_SHARES_GRPC_PROTOCOL=unix" +STORAGE_SHARES_GRPC_ADDR=/var/run/opencloud/storage-shares.sock" +GATEWAY_STORAGE_SHARES_ENDPOINT=unix:/var/run/opencloud/storage-shares.sock" + +APP_REGISTRY_GRPC_PROTOCOL=unix" +APP_REGISTRY_GRPC_ADDR=/var/run/opencloud/app-registry.sock" +GATEWAY_APP_REGISTRY_ENDPOINT=unix:/var/run/opencloud/app-registry.sock" + +OCM_GRPC_PROTOCOL=unix" +OCM_GRPC_ADDR=/var/run/opencloud/ocm.sock" +GATEWAY_OCM_ENDPOINT=unix:/var/run/opencloud/ocm.sock" + +// storage related +SETTINGS_STORAGE_GATEWAY_GRPC_ADDR="unix:/var/run/opencloud/storage-system.sock" +SETTINGS_STORAGE_GRPC_ADDR="unix:/var/run/opencloud/storage-system.sock" +STORAGE_SYSTEM_GRPC_PROTOCOL="unix" +STORAGE_SYSTEM_GRPC_ADDR="/var/run/opencloud/storage-system.sock" +SHARING_USER_CS3_PROVIDER_ADDR="unix:/var/run/opencloud/storage-system.sock" +SHARING_USER_JSONCS3_PROVIDER_ADDR="unix:/var/run/opencloud/storage-system.sock" +SHARING_PUBLIC_CS3_PROVIDER_ADDR="unix:/var/run/opencloud/storage-system.sock" +SHARING_PUBLIC_JSONCS3_PROVIDER_ADDR="unix:/var/run/opencloud/storage-system.sock" +``` + +## Storage Registry + +In order to add another storage provider the CS3 storage registry that is running as part of the CS3 gateway hes to be made aware of it. The easiest cleanest way to do it is to set `GATEWAY_STORAGE_REGISTRY_CONFIG_JSON=/path/to/storages.json` and list all storage providers like this: + +```json +{ + "eu.opencloud.api.storage-users": { + "providerid": "{storage-users-mount-uuid}", + "spaces": { + "personal": { + "mount_point": "/users", + "path_template": "/users/{{.Space.Owner.Id.OpaqueId}}" + }, + "project": { + "mount_point": "/projects", + "path_template": "/projects/{{.Space.Name}}" + } + } + }, + "eu.opencloud.api.storage-shares": { + "providerid": "a0ca6a90-a365-4782-871e-d44447bbc668", + "spaces": { + "virtual": { + "mount_point": "/users/{{.CurrentUser.Id.OpaqueId}}/Shares" + }, + "grant": { + "mount_point": "." + }, + "mountpoint": { + "mount_point": "/users/{{.CurrentUser.Id.OpaqueId}}/Shares", + "path_template": "/users/{{.CurrentUser.Id.OpaqueId}}/Shares/{{.Space.Name}}" + } + } + }, + "eu.opencloud.api.storage-publiclink": { + "providerid": "7993447f-687f-490d-875c-ac95e89a62a4", + "spaces": { + "grant": { + "mount_point": "." + }, + "mountpoint": { + "mount_point": "/public", + "path_template": "/public/{{.Space.Root.OpaqueId}}" + } + } + }, + "eu.opencloud.api.ocm": { + "providerid": "89f37a33-858b-45fa-8890-a1f2b27d90e1", + "spaces": { + "grant": { + "mount_point": "." + }, + "mountpoint": { + "mount_point": "/ocm", + "path_template": "/ocm/{{.Space.Root.OpaqueId}}" + } + } + }, + "eu.opencloud.api.storage-hello": { + "providerid": "hello-storage-id", + "spaces": { + "project": { + "mount_point": "/hello", + "path_template": "/hello/{{.Space.Name}}" + } + } + } +} +``` + +In the above replace `{storage-users-mount-uuid}` with the mount UUID that was generated for the storage-users service. You can find it in the `config.yaml` generated on by `opencloud init`. The last entry `eu.opencloud.api.storage-hello` and its `providerid` `"hello-storage-id"` are an example for in additional storage provider, in this case running `hellofs`, an example minimal storage driver. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/global_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/global_configvars.mdx new file mode 100644 index 00000000..2ff9b45c --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/global_configvars.mdx @@ -0,0 +1,110 @@ +#Environment variables with global scope available in multiple services + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|---| +`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 authenticate with the store. Only applies when store type 'nats-js-kv' is configured. | | +`OC_CACHE_AUTH_USERNAME` | 1.0.0 | string | The username to authenticate with the store. 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-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_STORE` | 1.0.0 | string | The type of the signing key store. Supported values are: 'redis-sentinel' and 'nats-js-kv'. See the text description for details. | nats-js-kv | +`OC_CACHE_STORE_NODES` | 1.0.0 | []string | A list of nodes to access the configured store. 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_TTL` | 1.0.0 | Duration | Default time to live for signing keys. See the Environment Variable Types description for more details. | 12h0m0s | +`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 Cache-Control] | +`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 PUT PATCH DELETE OPTIONS] | +`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. | | +`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 | 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 the 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 POLICIES_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. | | +`OC_GRPC_PROTOCOL` | 1.0.0 | string | The transport protocol of the GRPC service. | tcp | +`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 the NATS server should skip the client certificate verification during the TLS handshake. | 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_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_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. | /root/.opencloud/idm/ldap.crt | +`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 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 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_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. | ldaps://localhost:9235 | +`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_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_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 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 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 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_ISSUER` | 1.0.0 | string | The OIDC issuer URL to assign to the demo users. | 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 | +`OC_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_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_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_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_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. | 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` | 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` | 1.0.0 | string | Transfer secret for signing file up- and download requests. | | +`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 | URL, where OpenCloud is reachable for users. | 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` | 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 | \ No newline at end of file diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph.yaml new file mode 100644 index 00000000..95eacffa --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph.yaml @@ -0,0 +1,160 @@ +# Autogenerated +# Filename: graph.yaml + +loglevel: error +cache: + store: memory + nodes: + - 127.0.0.1:9233 + database: cache-roles + table: "" + ttl: 336h0m0s + disable_persistence: false + username: "" + password: "" +debug: + addr: 127.0.0.1:9124 + token: "" + pprof: false + zpages: false +http: + addr: 127.0.0.1:9120 + root: /graph + tls: + enabled: false + cert: "" + key: "" + apitoken: "" + cors: + allow_origins: + - '*' + allow_methods: + - GET + - POST + - PUT + - PATCH + - DELETE + - OPTIONS + allow_headers: + - Authorization + - Origin + - Content-Type + - Accept + - X-Requested-With + - X-Request-Id + - Purge + - Restore + allow_credentials: true +api: + group_members_patch_limit: 20 + graph_username_match: default + graph_assign_default_user_role: true + graph_identity_search_min_length: 3 + show_email_in_results: false +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +token_manager: + jwt_secret: "" +grpc_client_tls: null +application: + id: "" + displayname: OpenCloud +spaces: + webdav_base: https://localhost:9200 + webdav_path: /dav/spaces/ + default_quota: "1000000000" + extended_space_properties_cache_ttl: 60000000000 + users_cache_ttl: 60000000000 + groups_cache_ttl: 60000000000 + storage_users_address: eu.opencloud.api.storage-users + default_language: "" + translation_path: "" +identity: + backend: ldap + ldap: + uri: ldaps://localhost:9235 + cacert: /root/.opencloud/idm/ldap.crt + insecure: false + bind_dn: uid=libregraph,ou=sysusers,o=libregraph-idm + bind_password: "" + use_server_uuid: false + use_password_modify_exop: true + write_enabled: true + refint_enabled: false + user_base_dn: ou=users,o=libregraph-idm + user_search_scope: sub + user_filter: "" + user_objectclass: inetOrgPerson + user_mail_attribute: mail + user_displayname_attribute: displayName + user_name_attribute: uid + user_id_attribute: openCloudUUID + user_id_is_octet_string: false + user_type_attribute: openCloudUserType + user_enabled_attribute: openCloudUserEnabled + disable_user_mechanism: attribute + ldap_disabled_users_group_dn: cn=DisabledUsersGroup,ou=groups,o=libregraph-idm + group_base_dn: ou=groups,o=libregraph-idm + group_create_base_dn: ou=groups,o=libregraph-idm + group_search_scope: sub + group_filter: "" + group_objectclass: groupOfNames + group_name_attribute: cn + group_member_attribute: member + group_id_attribute: openCloudUUID + group_id_is_octet_string: false + education_resources_enabled: false + educationconfig: + school_base_dn: "" + school_search_scope: "" + school_filter: "" + school_objectclass: "" + school_name_attribute: "" + school_number_attribute: "" + school_id_attribute: "" + school_termination_min_grace_days: 0 +include_ocm_sharees: false +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" +unified_roles: + available_roles: + - b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5 + - a8d5fe5e-96e3-418d-825b-534dbdf22b99 + - fb6c3e19-e378-47e5-b277-9732f9de6e21 + - 58c63c02-1d89-4572-916a-870abc5a1b7d + - 2d00ce52-1fc2-4dbc-8b95-a73b73395f5a + - 1c996275-f1c9-4e71-abdf-a42f6495e960 + - 312c0871-5ef7-4b3a-85b6-0e4074c64049 +max_concurrency: 20 +keycloak: + base_path: "" + client_id: "" + client_secret: "" + client_realm: "" + user_realm: "" + insecure_skip_verify: false +service_account: + service_account_id: "" + service_account_secret: "" +metadata_config: + gateway_addr: eu.opencloud.api.storage-system + storage_addr: eu.opencloud.api.storage-system + system_user_id: "" + system_user_idp: internal + system_user_api_key: "" +user_soft_delete_retention_time: 0s +store: + nodes: + - 127.0.0.1:9233 + database: graph + username: "" + password: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_configvars.mdx new file mode 100644 index 00000000..e69aa0a0 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_configvars.mdx @@ -0,0 +1,116 @@ +Environment variables for the **graph** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`GRAPH_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`OC_CACHE_STORE`
`GRAPH_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`
`GRAPH_CACHE_STORE_NODES`| 1.0.0 |[]string|`A list of nodes to access the configured store. This has no effect when 'memory' store are 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]`| +|`GRAPH_CACHE_STORE_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`cache-roles`| +|`GRAPH_CACHE_STORE_TABLE`| 1.0.0 |string|`The database table the store should use.`|``| +|`OC_CACHE_TTL`
`GRAPH_CACHE_TTL`| 1.0.0 |Duration|`Time to live for cache records in the graph. Defaults to '336h' (2 weeks). See the Environment Variable Types description for more details.`|`336h0m0s`| +|`OC_CACHE_DISABLE_PERSISTENCE`
`GRAPH_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_AUTH_USERNAME`
`GRAPH_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_AUTH_PASSWORD`
`GRAPH_CACHE_AUTH_PASSWORD`| 1.0.0 |string|`The password to authenticate with the cache. Only applies when store type 'nats-js-kv' is configured.`|``| +|`GRAPH_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9124`| +|`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_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`| +|`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_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.`|``| +|`GRAPH_HTTP_API_TOKEN`| 1.0.0 |string|`An optional API bearer token`|``| +|`OC_CORS_ALLOW_ORIGINS`
`GRAPH_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_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_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`| +|`GRAPH_IDENTITY_SEARCH_MIN_LENGTH`| 1.0.0 |int|`The minimum length the search term needs to have for unprivileged users when searching for users or groups.`|`3`| +|`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_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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_JWT_SECRET`
`GRAPH_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`GRAPH_APPLICATION_ID`| 1.0.0 |string|`The OpenCloud application ID shown in the graph. All app roles are tied to this ID.`|``| +|`GRAPH_APPLICATION_DISPLAYNAME`| 1.0.0 |string|`The OpenCloud application name.`|`OpenCloud`| +|`OC_URL`
`GRAPH_SPACES_WEBDAV_BASE`| 1.0.0 |string|`The public facing URL of WebDAV.`|`https://localhost:9200`| +|`GRAPH_SPACES_WEBDAV_PATH`| 1.0.0 |string|`The WebDAV sub-path for spaces.`|`/dav/spaces/`| +|`GRAPH_SPACES_DEFAULT_QUOTA`| 1.0.0 |string|`The default quota in bytes.`|`1000000000`| +|`GRAPH_SPACES_EXTENDED_SPACE_PROPERTIES_CACHE_TTL`| 1.0.0 |int|`Max TTL in seconds for the spaces property cache.`|`60000000000`| +|`GRAPH_SPACES_USERS_CACHE_TTL`| 1.0.0 |int|`Max TTL in seconds for the spaces users cache.`|`60000000000`| +|`GRAPH_SPACES_GROUPS_CACHE_TTL`| 1.0.0 |int|`Max TTL in seconds for the spaces groups cache.`|`60000000000`| +|`GRAPH_SPACES_STORAGE_USERS_ADDRESS`| 1.0.0 |string|`The address of the storage-users service.`|`eu.opencloud.api.storage-users`| +|`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_TRANSLATION_PATH`
`GRAPH_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.`|``| +|`GRAPH_IDENTITY_BACKEND`| 1.0.0 |string|`The user identity backend to use. Supported backend types are 'ldap' and 'cs3'.`|`ldap`| +|`OC_LDAP_URI`
`GRAPH_LDAP_URI`| 1.0.0 |string|`URI of the LDAP Server to connect to. Supported URI schemes are 'ldaps://' and 'ldap://'`|`ldaps://localhost:9235`| +|`OC_LDAP_CACERT`
`GRAPH_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.`|`/root/.opencloud/idm/ldap.crt`| +|`OC_LDAP_INSECURE`
`GRAPH_LDAP_INSECURE`| 1.0.0 |bool|`Disable TLS certificate validation for the LDAP connections. Do not set this in production environments.`|`false`| +|`OC_LDAP_BIND_DN`
`GRAPH_LDAP_BIND_DN`| 1.0.0 |string|`LDAP DN to use for simple bind authentication with the target LDAP server.`|`uid=libregraph,ou=sysusers,o=libregraph-idm`| +|`OC_LDAP_BIND_PASSWORD`
`GRAPH_LDAP_BIND_PASSWORD`| 1.0.0 |string|`Password to use for authenticating the 'bind_dn'.`|``| +|`GRAPH_LDAP_SERVER_UUID`| 1.0.0 |bool|`If set to true, rely on the LDAP Server to generate a unique ID for users and groups, like when using 'entryUUID' as the user ID attribute.`|`false`| +|`GRAPH_LDAP_SERVER_USE_PASSWORD_MODIFY_EXOP`| 1.0.0 |bool|`Use the 'Password Modify Extended Operation' for updating user passwords.`|`true`| +|`OC_LDAP_SERVER_WRITE_ENABLED`
`GRAPH_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`| +|`GRAPH_LDAP_REFINT_ENABLED`| 1.0.0 |bool|`Signals that the server has the refint plugin enabled, which makes some actions not needed.`|`false`| +|`OC_LDAP_USER_BASE_DN`
`GRAPH_LDAP_USER_BASE_DN`| 1.0.0 |string|`Search base DN for looking up LDAP users.`|`ou=users,o=libregraph-idm`| +|`OC_LDAP_USER_SCOPE`
`GRAPH_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_FILTER`
`GRAPH_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`
`GRAPH_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_SCHEMA_MAIL`
`GRAPH_LDAP_USER_EMAIL_ATTRIBUTE`| 1.0.0 |string|`LDAP Attribute to use for the email address of users.`|`mail`| +|`OC_LDAP_USER_SCHEMA_DISPLAYNAME`
`GRAPH_LDAP_USER_DISPLAYNAME_ATTRIBUTE`| 1.0.0 |string|`LDAP Attribute to use for the display name of users.`|`displayName`| +|`OC_LDAP_USER_SCHEMA_USERNAME`
`GRAPH_LDAP_USER_NAME_ATTRIBUTE`| 1.0.0 |string|`LDAP Attribute to use for username of users.`|`uid`| +|`OC_LDAP_USER_SCHEMA_ID`
`GRAPH_LDAP_USER_UID_ATTRIBUTE`| 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`
`GRAPH_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 required when using the 'objectGUID' attribute of Active Directory for the user ID's.`|`false`| +|`OC_LDAP_USER_SCHEMA_USER_TYPE`
`GRAPH_LDAP_USER_TYPE_ATTRIBUTE`| 1.0.0 |string|`LDAP Attribute to distinguish between 'Member' and 'Guest' users. Default is 'openCloudUserType'.`|`openCloudUserType`| +|`OC_LDAP_USER_ENABLED_ATTRIBUTE`
`GRAPH_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_DISABLE_USER_MECHANISM`
`GRAPH_DISABLE_USER_MECHANISM`| 1.0.0 |string|`An option to control the behavior for disabling users. Supported 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. Default is 'attribute'.`|`attribute`| +|`OC_LDAP_DISABLED_USERS_GROUP_DN`
`GRAPH_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_GROUP_BASE_DN`
`GRAPH_LDAP_GROUP_BASE_DN`| 1.0.0 |string|`Search base DN for looking up LDAP groups.`|`ou=groups,o=libregraph-idm`| +|`GRAPH_LDAP_GROUP_CREATE_BASE_DN`| 1.0.0 |string|`Parent DN under which new groups are created. This DN needs to be subordinate to the 'GRAPH_LDAP_GROUP_BASE_DN'. This setting is only relevant when 'GRAPH_LDAP_SERVER_WRITE_ENABLED' is 'true'. It defaults to the value of 'GRAPH_LDAP_GROUP_BASE_DN'. All groups outside of this subtree are treated as readonly groups and cannot be updated.`|`ou=groups,o=libregraph-idm`| +|`OC_LDAP_GROUP_SCOPE`
`GRAPH_LDAP_GROUP_SEARCH_SCOPE`| 1.0.0 |string|`LDAP search scope to use when looking up groups. Supported scopes are 'base', 'one' and 'sub'.`|`sub`| +|`OC_LDAP_GROUP_FILTER`
`GRAPH_LDAP_GROUP_FILTER`| 1.0.0 |string|`LDAP filter to add to the default filters for group searches.`|``| +|`OC_LDAP_GROUP_OBJECTCLASS`
`GRAPH_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_GROUPNAME`
`GRAPH_LDAP_GROUP_NAME_ATTRIBUTE`| 1.0.0 |string|`LDAP Attribute to use for the name of groups.`|`cn`| +|`OC_LDAP_GROUP_SCHEMA_MEMBER`
`GRAPH_LDAP_GROUP_MEMBER_ATTRIBUTE`| 1.0.0 |string|`LDAP Attribute that is used for group members.`|`member`| +|`OC_LDAP_GROUP_SCHEMA_ID`
`GRAPH_LDAP_GROUP_ID_ATTRIBUTE`| 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`
`GRAPH_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 required when using the 'objectGUID' attribute of Active Directory for the group ID's.`|`false`| +|`GRAPH_LDAP_EDUCATION_RESOURCES_ENABLED`| 1.0.0 |bool|`Enable LDAP support for managing education related resources.`|`false`| +|`GRAPH_LDAP_SCHOOL_BASE_DN`| 1.0.0 |string|`Search base DN for looking up LDAP schools.`|``| +|`GRAPH_LDAP_SCHOOL_SEARCH_SCOPE`| 1.0.0 |string|`LDAP search scope to use when looking up schools. Supported scopes are 'base', 'one' and 'sub'.`|``| +|`GRAPH_LDAP_SCHOOL_FILTER`| 1.0.0 |string|`LDAP filter to add to the default filters for school searches.`|``| +|`GRAPH_LDAP_SCHOOL_OBJECTCLASS`| 1.0.0 |string|`The object class to use for schools in the default school search filter.`|``| +|`GRAPH_LDAP_SCHOOL_NAME_ATTRIBUTE`| 1.0.0 |string|`LDAP Attribute to use for the name of a school.`|``| +|`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`| +|`OC_ENABLE_OCM`
`GRAPH_INCLUDE_OCM_SHAREES`| 1.0.0 |bool|`Include OCM sharees when listing users.`|`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`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`GRAPH_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided GRAPH_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`GRAPH_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_AUTH_USERNAME`
`GRAPH_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_AUTH_PASSWORD`
`GRAPH_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.`|``| +|`GRAPH_AVAILABLE_ROLES`| 1.0.0 |[]string|`A comma separated list of roles that are available for assignment.`|`[b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5 a8d5fe5e-96e3-418d-825b-534dbdf22b99 fb6c3e19-e378-47e5-b277-9732f9de6e21 58c63c02-1d89-4572-916a-870abc5a1b7d 2d00ce52-1fc2-4dbc-8b95-a73b73395f5a 1c996275-f1c9-4e71-abdf-a42f6495e960 312c0871-5ef7-4b3a-85b6-0e4074c64049]`| +|`OC_MAX_CONCURRENCY`
`GRAPH_MAX_CONCURRENCY`| 1.0.0 |int|`The maximum number of concurrent requests the service will handle.`|`20`| +|`OC_KEYCLOAK_BASE_PATH`
`GRAPH_KEYCLOAK_BASE_PATH`| 1.0.0 |string|`The URL to access keycloak.`|``| +|`OC_KEYCLOAK_CLIENT_ID`
`GRAPH_KEYCLOAK_CLIENT_ID`| 1.0.0 |string|`The client id to authenticate with keycloak.`|``| +|`OC_KEYCLOAK_CLIENT_SECRET`
`GRAPH_KEYCLOAK_CLIENT_SECRET`| 1.0.0 |string|`The client secret to use in authentication.`|``| +|`OC_KEYCLOAK_CLIENT_REALM`
`GRAPH_KEYCLOAK_CLIENT_REALM`| 1.0.0 |string|`The realm the client is defined in.`|``| +|`OC_KEYCLOAK_USER_REALM`
`GRAPH_KEYCLOAK_USER_REALM`| 1.0.0 |string|`The realm users are defined.`|``| +|`OC_KEYCLOAK_INSECURE_SKIP_VERIFY`
`GRAPH_KEYCLOAK_INSECURE_SKIP_VERIFY`| 1.0.0 |bool|`Disable TLS certificate validation for Keycloak connections. Do not set this in production environments.`|`false`| +|`OC_SERVICE_ACCOUNT_ID`
`GRAPH_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`
`GRAPH_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| +|`GRAPH_STORAGE_GATEWAY_GRPC_ADDR`
`STORAGE_GATEWAY_GRPC_ADDR`| 4.0.0 |string|`GRPC address of the STORAGE-SYSTEM service.`|`eu.opencloud.api.storage-system`| +|`GRAPH_STORAGE_GRPC_ADDR`
`STORAGE_GRPC_ADDR`| 4.0.0 |string|`GRPC address of the STORAGE-SYSTEM service.`|`eu.opencloud.api.storage-system`| +|`OC_SYSTEM_USER_ID`
`GRAPH_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`
`GRAPH_SYSTEM_USER_IDP`| 4.0.0 |string|`IDP of the OpenCloud STORAGE-SYSTEM system user.`|`internal`| +|`OC_SYSTEM_USER_API_KEY`| 4.0.0 |string|`API key for the STORAGE-SYSTEM system user.`|``| +|`GRAPH_USER_SOFT_DELETE_RETENTION_TIME`| 4.0.0 |Duration|`The time after which a soft-deleted user is permanently deleted. If set to 0 (default), there is no soft delete retention time and users are deleted immediately after being soft-deleted. If set to a positive value, the user will be kept in the system for that duration before being permanently deleted.`|`0s`| +|`OC_PERSISTENT_STORE_NODES`
`GRAPH_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]`| +|`GRAPH_STORE_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`graph`| +|`OC_PERSISTENT_STORE_AUTH_USERNAME`
`GRAPH_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_AUTH_PASSWORD`
`GRAPH_STORE_AUTH_PASSWORD`| 1.0.0 |string|`The password to authenticate with the store. Only applies when store type 'nats-js-kv' is configured.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_readme.mdx new file mode 100755 index 00000000..63f21600 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/graph_readme.mdx @@ -0,0 +1,217 @@ +--- +title: Graph +date: 2026-01-15T10:35:01.391003225Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/graph +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The graph service provides the Graph API which is a RESTful web API used to access OpenCloud +resources. It is inspired by the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/use-the-api) +and can be used by clients or other services or extensions. Visit the [Libre Graph API](https://docs.opencloud.eu/swagger/libre-graph-api/) +for a detailed specification of the API implemented by the graph service. + + +## Table of Contents + +* [Sequence Diagram](#sequence-diagram) +* [Users and Groups API](#users-and-groups-api) + * [LDAP Configuration](#ldap-configuration) + * [Read-Only Access to Existing LDAP Servers](#read-only-access-to-existing-ldap-servers) + * [Using a Write Enabled LDAP Server](#using-a-write-enabled-ldap-server) +* [Query Filters Provided by the Graph API](#query-filters-provided-by-the-graph-api) +* [Caching](#caching) +* [Keycloak Configuration For The Personal Data Export](#keycloak-configuration-for-the-personal-data-export) + * [Keycloak Client Configuration](#keycloak-client-configuration) +* [Translations](#translations) + * [Translation Rules](#translation-rules) +* [Default Language](#default-language) +* [Unified Role Management](#unified-role-management) + +## Sequence Diagram + +The following image gives an overview of the scenario when a client requests to list available spaces the user has access to. To do so, the client is directed with his request automatically via the proxy service to the graph service. + + + +## Users and Groups API + +The graph service provides endpoints for querying users and groups. It features two different backend implementations: + * `ldap`: This is currently the default backend. It queries user and group information from an + LDAP server. Depending on the configuration, it can also be used to manage (create, update, + delete) users and groups provided by an LDAP server. + * `cs3`: This backend queries users and groups using the CS3 identity APIs as implemented by the + `users` and `groups` service. This backend is currently still experimental and only implements a + subset of the Libre Graph API. It should not be used in production. + +### LDAP Configuration + +The LDAP backend is configured using a set of environment variables. A detailed list of all the +available configuration options can be found in the [documentation](https://docs.opencloud.eu/docs/dev/server/services/graph/environment-variables). +The LDAP related options are prefixed with `OC_LDAP_` (or `GRAPH_LDAP_` for settings specific to graph service). + +#### Read-Only Access to Existing LDAP Servers + +To connect the graph service to an existing LDAP server, set `OC_LDAP_SERVER_WRITE_ENABLED` to +`false` to prevent the graph service from sending write operations to the LDAP server. Also set the +various `OC_LDAP_*` environment variables to match the configuration of the LDAP server you are connecting +to. A more detailed explanation can be found [here](https://docs.opencloud.eu/docs/admin/configuration/authentication-and-user-management/. + +#### Using a Write Enabled LDAP Server + +To use the graph service for managing (create, update, delete) users and groups, a write enabled LDAP +server is required. In the default configuration, the graph service will use the simple LDAP server +that is bundled with OpenCloud in the `idm` service which provides all the required features. +It is also possible to setup up an external LDAP server with write access for use with OpenCloud. It is +recommend to use OpenLDAP for this. The LDAP server needs to fulfill a couple of requirements with +respect to the available schema: + * The LDAP server must provide the `inetOrgPerson` object class for users and the `groupOfNames` + object class for groups. + * The graph service maintains a few additional attributes for users and groups that are not + available in the standard LDAP schema. An schema file, ready to use with OpenLDAP, defining those + additional attributes is available [here](https://github.com/opencloud-eu/opencloud-compose/blob/main/config/ldap/schemas/10_opencloud_schema.ldif) + +## Query Filters Provided by the Graph API + +Some API endpoints provided by the graph service allow to specify query filters. The filter syntax +is based on the [OData Specification](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptionfilter). +See the [Libre Graph API](https://docs.opencloud.eu/swagger/libre-graph-api/#/users/ListUsers) for examples +on the filters supported when querying users. + +## Caching + +The `graph` service can use a configured store via `GRAPH_CACHE_STORE`. Possible stores are: + - `memory`: Basic in-memory store and the default. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + +## Keycloak Configuration For The Personal Data Export + +If Keycloak is used for authentication, GDPR regulations require to add all personal identifiable information that Keycloak has about the user to the personal data export. To do this, the following environment variables must be set: + +* `OC_KEYCLOAK_BASE_PATH` - The URL to the keycloak instance. +* `OC_KEYCLOAK_CLIENT_ID` - The client ID of the client that is used to authenticate with keycloak, this client has to be able to list users and get the credential data. +* `OC_KEYCLOAK_CLIENT_SECRET` - The client secret of the client that is used to authenticate with keycloak. +* `OC_KEYCLOAK_CLIENT_REALM` - The realm the client is defined in. +* `OC_KEYCLOAK_USER_REALM` - The realm the OpenCloud users are defined in. +* `OC_KEYCLOAK_INSECURE_SKIP_VERIFY` - If set to true, the TLS certificate of the keycloak instance is not verified. + +### Keycloak Client Configuration + +The client that is used to authenticate with keycloak has to be able to list users and get the credential data. To do this, the following roles have to be assigned to the client and they have to be about the realm that contains the OpenCloud users: + +* `view-users` +* `view-identity-providers` +* `view-realm` +* `view-clients` +* `view-events` +* `view-authorization` + +:::note +These roles are only available to assign if the client is in the `master` realm. +::: + +## Translations + +The `graph` service has embedded translations sourced via transifex to provide a basic set of translated languages. These embedded translations are available for all deployment scenarios. In addition, the service supports custom translations, though it is currently not possible to just add custom translations to embedded ones. If custom translations are configured, the embedded ones are not used. To configure custom translations, the `GRAPH_TRANSLATION_PATH` environment variable needs to point to a base folder that will contain the translation files. This path must be available from all instances of the graph service, a shared storage is recommended. Translation files must be of type [.po](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html#PO-Files) or [.mo](https://www.gnu.org/software/gettext/manual/html_node/Binaries.html). For each language, the filename needs to be `graph.po` (or `graph.mo`) and stored in a folder structure defining the language code. In general the path/name pattern for a translation file needs to be: + +```text +{GRAPH_TRANSLATION_PATH}/{language-code}/LC_MESSAGES/graph.po +``` + +The language code pattern is composed of `language[_territory]` where `language` is the base language and `_territory` is optional and defines a country. + +For example, for the language `de`, one needs to place the corresponding translation files to `{GRAPH_TRANSLATION_PATH}/de_DE/LC_MESSAGES/graph.po`. + + + +:::warning +For the time being, the embedded OpenCloud Web frontend only supports the main language code but does not handle any territory. When strings are available in the language code `language_territory`, the web frontend does not see it as it only requests `language`. In consequence, any translations made must exist in the requested `language` to avoid a fallback to the default. +::: + +### Translation Rules + +* If a requested language code is not available, the service tries to fall back to the base language if available. For example, if the requested language-code `de_DE` is not available, the service tries to fall back to translations in the `de` folder. +* If the base language `de` is also not available, the service falls back to the system's default English (`en`), +which is the source of the texts provided by the code. + +## Default Language + +The default language can be defined via the `OC_DEFAULT_LANGUAGE` environment variable. See the `settings` service for a detailed description. + +## Unified Role Management + +Unified Roles are roles granted a user for sharing and can be enabled or disabled. A CLI command is provided to list existing roles and their state among other data. + +:::info +Note that a disabled role does not lose previously assigned permissions. It only means that the role is not available for new assignments. +::: + +The following roles are **enabled** by default: + +- `UnifiedRoleViewerID` +- `UnifiedRoleSpaceViewer` +- `UnifiedRoleEditor` +- `UnifiedRoleSpaceEditor` +- `UnifiedRoleFileEditor` +- `UnifiedRoleEditorLite` +- `UnifiedRoleManager` + +The following role is **disabled** by default: + +- `UnifiedRoleSecureViewer` + +To enable disabled roles like the `UnifiedRoleSecureViewer`, you must provide the UID(s) by one of the following methods: + +- Using the `GRAPH_AVAILABLE_ROLES` environment variable. +- Setting the `available_roles` configuration value. + +The following CLI command simplifies the process of finding out which UID belongs to which role: + +```bash +opencloud graph list-unified-roles +``` + +The output of this command includes the following information for each role: + +* `UID`\ + The unique identifier of the role. +* `Enabled`\ + Whether the role is enabled or not. +* `Description`\ + A short description of the role. +* `Condition` +* `Allowed resource actions` + +**Example output (shortned)** + +```bash ++--------------------------------------+----------+--------------------------------+--------------------------------+------------------------------------------+ +| UID | ENABLED | DESCRIPTION | CONDITION | ALLOWED RESOURCE ACTIONS | ++--------------------------------------+----------+--------------------------------+--------------------------------+------------------------------------------+ +| a8d5fe5e-96e3-418d-825b-534dbdf22b99 | enabled | View and download. | exists @Resource.Root | libre.graph/driveItem/path/read | +| | | | | libre.graph/driveItem/quota/read | +| | | | | libre.graph/driveItem/content/read | +| | | | | libre.graph/driveItem/permissions/read | +| | | | | libre.graph/driveItem/children/read | +| | | | | libre.graph/driveItem/deleted/read | +| | | | | libre.graph/driveItem/basic/read | ++--------------------------------------+----------+--------------------------------+--------------------------------+------------------------------------------+ +``` + + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups.yaml new file mode 100644 index 00000000..eacfc14e --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups.yaml @@ -0,0 +1,63 @@ +# Autogenerated +# Filename: groups.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9161 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9160 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +skip_user_groups_in_token: false +driver: ldap +drivers: + ldap: + uri: ldaps://localhost:9235 + ca_cert: /root/.opencloud/idm/ldap.crt + insecure: false + bind_dn: uid=reva,ou=sysusers,o=libregraph-idm + bind_password: "" + user_base_dn: ou=users,o=libregraph-idm + group_base_dn: ou=groups,o=libregraph-idm + user_scope: sub + group_scope: sub + group_substring_filter_type: any + user_filter: "" + group_filter: "" + user_object_class: inetOrgPerson + group_object_class: groupOfNames + idp: https://localhost:9200 + user_schema: + id: openCloudUUID + id_is_octet_string: false + mail: mail + display_name: displayname + user_name: uid + group_schema: + id: openCloudUUID + id_is_octet_string: false + mail: mail + display_name: cn + group_name: cn + member: member + owncloudsql: + db_username: owncloud + db_password: "" + db_host: mysql + db_port: 3306 + db_name: owncloud + idp: https://localhost:9200 + nobody: 90 + join_username: false + join_owncloud_uuid: false + enable_medial_search: false diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_configvars.mdx new file mode 100644 index 00000000..05f49633 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_configvars.mdx @@ -0,0 +1,53 @@ +Environment variables for the **groups** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`GROUPS_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`GROUPS_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9161`| +|`GROUPS_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`GROUPS_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`GROUPS_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`GROUPS_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9160`| +|`OC_GRPC_PROTOCOL`
`GROUPS_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`OC_JWT_SECRET`
`GROUPS_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`GROUPS_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the loading of user's group memberships from the reva access token.`|`false`| +|`GROUPS_DRIVER`| 1.0.0 |string|`The driver which should be used by the groups service. Supported values are 'ldap' and 'owncloudsql'.`|`ldap`| +|`OC_LDAP_URI`
`GROUPS_LDAP_URI`| 1.0.0 |string|`URI of the LDAP Server to connect to. Supported URI schemes are 'ldaps://' and 'ldap://'`|`ldaps://localhost:9235`| +|`OC_LDAP_CACERT`
`GROUPS_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.`|`/root/.opencloud/idm/ldap.crt`| +|`OC_LDAP_INSECURE`
`GROUPS_LDAP_INSECURE`| 1.0.0 |bool|`Disable TLS certificate validation for the LDAP connections. Do not set this in production environments.`|`false`| +|`OC_LDAP_BIND_DN`
`GROUPS_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`
`GROUPS_LDAP_BIND_PASSWORD`| 1.0.0 |string|`Password to use for authenticating the 'bind_dn'.`|``| +|`OC_LDAP_USER_BASE_DN`
`GROUPS_LDAP_USER_BASE_DN`| 1.0.0 |string|`Search base DN for looking up LDAP users.`|`ou=users,o=libregraph-idm`| +|`OC_LDAP_GROUP_BASE_DN`
`GROUPS_LDAP_GROUP_BASE_DN`| 1.0.0 |string|`Search base DN for looking up LDAP groups.`|`ou=groups,o=libregraph-idm`| +|`OC_LDAP_USER_SCOPE`
`GROUPS_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_GROUP_SCOPE`
`GROUPS_LDAP_GROUP_SCOPE`| 1.0.0 |string|`LDAP search scope to use when looking up groups. Supported scopes are 'base', 'one' and 'sub'.`|`sub`| +|`LDAP_GROUP_SUBSTRING_FILTER_TYPE`
`GROUPS_LDAP_GROUP_SUBSTRING_FILTER_TYPE`| 1.0.0 |string|`Type of substring search filter to use for substring searches for groups. Supported values are 'initial', 'final' and 'any'. The value 'initial' is used for doing prefix only searches, 'final' for doing suffix only searches or 'any' for doing full substring searches`|`any`| +|`OC_LDAP_USER_FILTER`
`GROUPS_LDAP_USER_FILTER`| 1.0.0 |string|`LDAP filter to add to the default filters for user search like '(objectclass=openCloudUser)'.`|``| +|`OC_LDAP_GROUP_FILTER`
`GROUPS_LDAP_GROUP_FILTER`| 1.0.0 |string|`LDAP filter to add to the default filters for group searches.`|``| +|`OC_LDAP_USER_OBJECTCLASS`
`GROUPS_LDAP_USER_OBJECTCLASS`| 1.0.0 |string|`The object class to use for users in the default user search filter ('inetOrgPerson').`|`inetOrgPerson`| +|`OC_LDAP_GROUP_OBJECTCLASS`
`GROUPS_LDAP_GROUP_OBJECTCLASS`| 1.0.0 |string|`The object class to use for groups in the default group search filter ('groupOfNames').`|`groupOfNames`| +|`OC_URL`
`OC_OIDC_ISSUER`
`GROUPS_IDP_URL`| 1.0.0 |string|`The identity provider value to set in the group IDs of the CS3 group objects for groups returned by this group provider.`|`https://localhost:9200`| +|`OC_LDAP_USER_SCHEMA_ID`
`GROUPS_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`
`GROUPS_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`
`GROUPS_LDAP_USER_SCHEMA_MAIL`| 1.0.0 |string|`LDAP Attribute to use for the email address of users.`|`mail`| +|`OC_LDAP_USER_SCHEMA_DISPLAYNAME`
`GROUPS_LDAP_USER_SCHEMA_DISPLAYNAME`| 1.0.0 |string|`LDAP Attribute to use for the displayname of users.`|`displayname`| +|`OC_LDAP_USER_SCHEMA_USERNAME`
`GROUPS_LDAP_USER_SCHEMA_USERNAME`| 1.0.0 |string|`LDAP Attribute to use for username of users.`|`uid`| +|`OC_LDAP_GROUP_SCHEMA_ID`
`GROUPS_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`
`GROUPS_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`
`GROUPS_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_DISPLAYNAME`
`GROUPS_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`
`GROUPS_LDAP_GROUP_SCHEMA_GROUPNAME`| 1.0.0 |string|`LDAP Attribute to use for the name of groups.`|`cn`| +|`OC_LDAP_GROUP_SCHEMA_MEMBER`
`GROUPS_LDAP_GROUP_SCHEMA_MEMBER`| 1.0.0 |string|`LDAP Attribute that is used for group members.`|`member`| +|`GROUPS_OWNCLOUDSQL_DB_USERNAME`| 1.0.0 |string|`Database user to use for authenticating with the owncloud database.`|`owncloud`| +|`GROUPS_OWNCLOUDSQL_DB_PASSWORD`| 1.0.0 |string|`Password for the database user.`|``| +|`GROUPS_OWNCLOUDSQL_DB_HOST`| 1.0.0 |string|`Hostname of the database server.`|`mysql`| +|`GROUPS_OWNCLOUDSQL_DB_PORT`| 1.0.0 |int|`Network port to use for the database connection.`|`3306`| +|`GROUPS_OWNCLOUDSQL_DB_NAME`| 1.0.0 |string|`Name of the owncloud database.`|`owncloud`| +|`GROUPS_OWNCLOUDSQL_IDP`| 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`| +|`GROUPS_OWNCLOUDSQL_NOBODY`| 1.0.0 |int64|`Fallback number if no numeric UID and GID properties are provided.`|`90`| +|`GROUPS_OWNCLOUDSQL_JOIN_USERNAME`| 1.0.0 |bool|`Join the user properties table to read usernames.`|`false`| +|`GROUPS_OWNCLOUDSQL_JOIN_OWNCLOUD_UUID`| 1.0.0 |bool|`Join the user properties table to read user IDs.`|`false`| +|`GROUPS_OWNCLOUDSQL_ENABLE_MEDIAL_SEARCH`| 1.0.0 |bool|`Allow 'medial search' when searching for users instead of just doing a prefix search. This allows finding 'Alice' when searching for 'lic'.`|`false`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_readme.mdx new file mode 100755 index 00000000..5136e9a7 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/groups_readme.mdx @@ -0,0 +1,51 @@ +--- +title: Groups +date: 2026-01-15T10:35:01.391209024Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/groups +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `groups` service provides the CS3 Groups API for OpenCloud. It is responsible for managing group information and memberships within the OpenCloud instance. + +This service implements the CS3 identity group provider interface, allowing other services to query and manage groups. It works as a backend provider for the `graph` service when using the CS3 backend mode. + + +## Table of Contents + +* [Backend Integration](#backend-integration) +* [API](#api) +* [Usage](#usage) +* [Scalability](#scalability) + +## Backend Integration + +The groups service can work with different storage backends: +- LDAP integration through the graph service +- Direct CS3 API implementation + +When using the `graph` service with the CS3 backend (`GRAPH_IDENTITY_BACKEND=cs3`), the graph service queries group information through this service. + +## API + +The service provides CS3 gRPC APIs for: +- Listing groups +- Getting group information +- Finding groups by name or ID +- Managing group memberships + +## Usage + +The groups service is only used internally by other OpenCloud services and not being accessed directly by clients. The `frontend` and `ocs` services translate HTTP API requests into CS3 API calls to this service. + +## Scalability + +Since the groups service queries backend systems (like LDAP through the configured identity backend), it can be scaled horizontally without additional configuration when using stateless backends. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm.yaml new file mode 100644 index 00000000..22b8db7c --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm.yaml @@ -0,0 +1,22 @@ +# Autogenerated +# Filename: idm.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9239 + token: "" + pprof: false + zpages: false +idm: + ldaps_addr: 127.0.0.1:9235 + cert: /root/.opencloud/idm/ldap.crt + key: /root/.opencloud/idm/ldap.key + database: /root/.opencloud/idm/idm.boltdb +create_demo_users: false +demo_users_issuer_url: https://localhost:9200 +service_user_passwords: + admin_password: "" + idm_password: "" + reva_password: "" + idp_password: "" +admin_user_id: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_configvars.mdx new file mode 100644 index 00000000..0c7aacfa --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_configvars.mdx @@ -0,0 +1,20 @@ +Environment variables for the **idm** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`IDM_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`IDM_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9239`| +|`IDM_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`IDM_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`IDM_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`IDM_LDAPS_ADDR`| 1.0.0 |string|`Listen address for the LDAPS listener (ip-addr:port).`|`127.0.0.1:9235`| +|`IDM_LDAPS_CERT`| 1.0.0 |string|`File name of the TLS server certificate for the LDAPS listener. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idm.`|`/root/.opencloud/idm/ldap.crt`| +|`IDM_LDAPS_KEY`| 1.0.0 |string|`File name for the TLS certificate key for the server certificate. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idm.`|`/root/.opencloud/idm/ldap.key`| +|`IDM_DATABASE_PATH`| 1.0.0 |string|`Full path to the IDM backend database. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idm.`|`/root/.opencloud/idm/idm.boltdb`| +|`IDM_CREATE_DEMO_USERS`| 1.0.0 |bool|`Flag to enable or disable the creation of the demo users.`|`false`| +|`OC_URL`
`OC_OIDC_ISSUER`| 1.0.0 |string|`The OIDC issuer URL to assign to the demo users.`|`https://localhost:9200`| +|`IDM_ADMIN_PASSWORD`| 1.0.0 |string|`Password to set for the OpenCloud 'admin' user. Either cleartext or an argon2id hash.`|``| +|`IDM_SVC_PASSWORD`| 1.0.0 |string|`Password to set for the 'idm' service user. Either cleartext or an argon2id hash.`|``| +|`IDM_REVASVC_PASSWORD`| 1.0.0 |string|`Password to set for the 'reva' service user. Either cleartext or an argon2id hash.`|``| +|`IDM_IDPSVC_PASSWORD`| 1.0.0 |string|`Password to set for the 'idp' service user. Either cleartext or an argon2id hash.`|``| +|`OC_ADMIN_USER_ID`
`IDM_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.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_readme.mdx new file mode 100755 index 00000000..93010c8b --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idm_readme.mdx @@ -0,0 +1,27 @@ +--- +title: IDM +date: 2026-01-15T10:35:01.391317834Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/idm +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The IDM service provides a minimal LDAP Service, based on [Libregraph idm](https://github.com/libregraph/idm), for OpenCloud. It is started as part of the default configuration and serves as a central place for storing user and group information. + +It is mainly targeted at small OpenCloud installations. For larger setups it is recommended to replace IDM with a “real” LDAP server or to switch to an external identity management solution. + +IDM listens on port 9235 by default. In the default configuration it only accepts TLS-protected connections (LDAPS). The BaseDN of the LDAP tree is `o=libregraph-idm`. IDM gives LDAP write permissions to a single user (DN: `uid=libregraph,ou=sysusers,o=libregraph-idm`). Any other authenticated user has read-only access. IDM stores its data in a boltdb file `idm/idm.boltdb` inside the OpenCloud base data directory. + +Note: IDM is limited in its functionality. It only supports a subset of the LDAP operations (namely `BIND`, `SEARCH`, `ADD`, `MODIFY`, `DELETE`). Also, IDM currently does not do any schema verification (like. structural vs. auxiliary object classes, require and option attributes, syntax checks, …). Therefore it is not meant as a general purpose LDAP server. + +## Table of Contents + + + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp.yaml new file mode 100644 index 00000000..18419c03 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp.yaml @@ -0,0 +1,113 @@ +# Autogenerated +# Filename: idp.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9134 + token: "" + pprof: false + zpages: false +http: + addr: 127.0.0.1:9130 + root: / + tls_cert: /root/.opencloud/idp/server.crt + tls_key: /root/.opencloud/idp/server.key + tls: false +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +machine_auth_api_key: "" +asset: + asset: "" + login-background-url: "" +idp: + iss: https://localhost:9200 + identity_manager: ldap + uri_base_path: "" + sign_in_uri: "" + signed_out_uri: "" + authorization_endpoint_uri: "" + ldap_insecure: false + trusted_proxy: [] + allow_scope: [] + allow_client_guests: false + allow_dynamic_client_registration: false + encrypt_secret_file: /root/.opencloud/idp/encryption.key + listen: "" + identifierdefaultbannerlogo: "" + default_sign_in_page_text: "" + default_logo_target_uri: https://opencloud.eu + identifierdefaultusernamehinttext: "" + identifieruilocales: [] + signing_kid: private-key + signing_method: PS256 + signing_private_key_files: + - /root/.opencloud/idp/private-key.pem + validation_keys_path: "" + cookiebackenduri: "" + cookienames: [] + cookiesamesite: 3 + access_token_duration_seconds: 300 + id_token_duration_seconds: 300 + refresh_token_duration_seconds: 2592000 + dynamic_client_secret_duration_seconds: 0 +clients: +- id: web + name: OpenCloud Web App + trusted: true + secret: "" + redirect_uris: + - '{{OC_URL}}/' + - '{{OC_URL}}/oidc-callback.html' + - '{{OC_URL}}/oidc-silent-redirect.html' + post_logout_redirect_uris: [] + origins: + - '{{OC_URL}}' + application_type: "" +- id: OpenCloudDesktop + name: OpenCloud Desktop Client + trusted: false + secret: "" + redirect_uris: + - http://127.0.0.1 + - http://localhost + post_logout_redirect_uris: [] + origins: [] + application_type: native +- id: OpenCloudAndroid + name: OpenCloud Android App + trusted: false + secret: "" + redirect_uris: + - oc://android.opencloud.eu + post_logout_redirect_uris: + - oc://android.opencloud.eu + origins: [] + application_type: native +- id: OpenCloudIOS + name: OpenCloud iOS App + trusted: false + secret: "" + redirect_uris: + - oc://ios.opencloud.eu + post_logout_redirect_uris: + - oc://ios.opencloud.eu + origins: [] + application_type: native +ldap: + uri: ldaps://localhost:9235 + cacert: /root/.opencloud/idm/ldap.crt + bind_dn: uid=idp,ou=sysusers,o=libregraph-idm + bind_password: "" + base_dn: ou=users,o=libregraph-idm + scope: sub + login_attribute: uid + email_attribute: mail + name_attribute: displayName + uuid_attribute: openCloudUUID + uuid_attribute_type: text + user_enabled_attribute: openCloudUserEnabled + filter: "" + objectclass: inetOrgPerson diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_configvars.mdx new file mode 100644 index 00000000..4c7bb4c2 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_configvars.mdx @@ -0,0 +1,55 @@ +Environment variables for the **idp** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`IDP_PASSWORD_RESET_URI`| 1.0.0 |string|`The URI where a user can reset their password.`|``| +|`OC_LOG_LEVEL`
`IDP_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`IDP_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9134`| +|`IDP_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`IDP_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`IDP_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`IDP_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9130`| +|`IDP_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/`| +|`IDP_TRANSPORT_TLS_CERT`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the IDP service. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idp.`|`/root/.opencloud/idp/server.crt`| +|`IDP_TRANSPORT_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 IDP service. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idp.`|`/root/.opencloud/idp/server.key`| +|`IDP_TLS`| 1.0.0 |bool|`Disable or Enable HTTPS for the communication between the Proxy service and the IDP service. If set to 'true', the key and cert files need to be configured and present.`|`false`| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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_MACHINE_AUTH_API_KEY`
`IDP_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.`|``| +|`IDP_ASSET_PATH`| 1.0.0 |string|`Serve IDP assets from a path on the filesystem instead of the builtin assets.`|``| +|`IDP_LOGIN_BACKGROUND_URL`| 1.0.0 |string|`Configure an alternative URL to the background image for the login page.`|``| +|`OC_URL`
`OC_OIDC_ISSUER`
`IDP_ISS`| 1.0.0 |string|`The OIDC issuer URL to use.`|`https://localhost:9200`| +|`IDP_IDENTITY_MANAGER`| 1.0.0 |string|`The identity manager implementation to use. Supported identity managers are 'ldap', 'cs3', 'libregraph' and 'guest'.`|`ldap`| +|`IDP_URI_BASE_PATH`| 1.0.0 |string|`IDP uri base path (defaults to '').`|``| +|`IDP_SIGN_IN_URI`| 1.0.0 |string|`IDP sign-in url.`|``| +|`IDP_SIGN_OUT_URI`| 1.0.0 |string|`IDP sign-out url.`|``| +|`IDP_ENDPOINT_URI`| 1.0.0 |string|`URL of the IDP endpoint.`|``| +|`OC_LDAP_INSECURE`
`IDP_INSECURE`| 1.0.0 |bool|`Disable TLS certificate validation for the LDAP connections. Do not set this in production environments.`|`false`| +|`IDP_ALLOW_CLIENT_GUESTS`| 1.0.0 |bool|`Allow guest clients to access OpenCloud.`|`false`| +|`IDP_ALLOW_DYNAMIC_CLIENT_REGISTRATION`| 1.0.0 |bool|`Allow dynamic client registration.`|`false`| +|`IDP_ENCRYPTION_SECRET_FILE`| 1.0.0 |string|`Path to the encryption secret file, if unset, a new certificate will be autogenerated upon each restart, thus invalidating all existing sessions. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idp.`|`/root/.opencloud/idp/encryption.key`| +|`IDP_DEFAULT_SIGNIN_PAGE_TEXT`| 2.0.0 |string|``|``| +|`IDP_DEFAULT_LOGO_TARGET_URI`| 4.0.0 |string|`Default logo target URI.`|`https://opencloud.eu`| +|`IDP_SIGNING_KID`| 1.0.0 |string|`Value of the KID (Key ID) field which is used in created tokens to uniquely identify the signing-private-key.`|`private-key`| +|`IDP_SIGNING_METHOD`| 1.0.0 |string|`Signing method of IDP requests like 'PS256'`|`PS256`| +|`IDP_SIGNING_PRIVATE_KEY_FILES`| 1.0.0 |[]string|`A list of private key files for signing IDP requests. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idp. See the Environment Variable Types description for more details.`|`[/root/.opencloud/idp/private-key.pem]`| +|`IDP_VALIDATION_KEYS_PATH`| 1.0.0 |string|`Path to validation keys for IDP requests.`|``| +|`IDP_ACCESS_TOKEN_EXPIRATION`| 1.0.0 |uint64|`'Access token lifespan in seconds (time before an access token is expired).'`|`300`| +|`IDP_ID_TOKEN_EXPIRATION`| 1.0.0 |uint64|`ID token lifespan in seconds (time before an ID token is expired).`|`300`| +|`IDP_REFRESH_TOKEN_EXPIRATION`| 1.0.0 |uint64|`Refresh token lifespan in seconds (time before an refresh token is expired). This also limits the duration of an idle offline session.`|`2592000`| +|`IDP_DYNAMIC_CLIENT_SECRET_DURATION`| 1.0.0 |uint64|`Lifespan in seconds of a dynamically registered OIDC client.`|`0`| +|`OC_LDAP_URI`
`IDP_LDAP_URI`| 1.0.0 |string|`Url of the LDAP service to use as IDP.`|`ldaps://localhost:9235`| +|`OC_LDAP_CACERT`
`IDP_LDAP_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 LDAP service. If not defined, the root directory derives from $OC_BASE_DATA_PATH/idp.`|`/root/.opencloud/idm/ldap.crt`| +|`OC_LDAP_BIND_DN`
`IDP_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`
`IDP_LDAP_BIND_PASSWORD`| 1.0.0 |string|`Password to use for authenticating the 'bind_dn'.`|``| +|`OC_LDAP_USER_BASE_DN`
`IDP_LDAP_BASE_DN`| 1.0.0 |string|`Search base DN for looking up LDAP users.`|`ou=users,o=libregraph-idm`| +|`OC_LDAP_USER_SCOPE`
`IDP_LDAP_SCOPE`| 1.0.0 |string|`LDAP search scope to use when looking up users. Supported scopes are 'base', 'one' and 'sub'.`|`sub`| +|`IDP_LDAP_LOGIN_ATTRIBUTE`| 1.0.0 |string|`LDAP User attribute to use for login like 'uid'.`|`uid`| +|`OC_LDAP_USER_SCHEMA_MAIL`
`IDP_LDAP_EMAIL_ATTRIBUTE`| 1.0.0 |string|`LDAP User email attribute like 'mail'.`|`mail`| +|`OC_LDAP_USER_SCHEMA_USERNAME`
`IDP_LDAP_NAME_ATTRIBUTE`| 1.0.0 |string|`LDAP User name attribute like 'displayName'.`|`displayName`| +|`OC_LDAP_USER_SCHEMA_ID`
`IDP_LDAP_UUID_ATTRIBUTE`| 1.0.0 |string|`LDAP User UUID attribute like 'uid'.`|`openCloudUUID`| +|`IDP_LDAP_UUID_ATTRIBUTE_TYPE`| 1.0.0 |string|`LDAP User uuid attribute type like 'text'.`|`text`| +|`OC_LDAP_USER_ENABLED_ATTRIBUTE`
`IDP_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`
`IDP_LDAP_FILTER`| 1.0.0 |string|`LDAP filter to add to the default filters for user search like '(objectclass=openCloudUser)'.`|``| +|`OC_LDAP_USER_OBJECTCLASS`
`IDP_LDAP_OBJECTCLASS`| 1.0.0 |string|`LDAP User ObjectClass like 'inetOrgPerson'.`|`inetOrgPerson`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_readme.mdx new file mode 100755 index 00000000..d95980a0 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/idp_readme.mdx @@ -0,0 +1,102 @@ +--- +title: IDP +date: 2026-01-15T10:35:01.391416094Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/idp +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +This service provides a builtin minimal OpenID Connect provider based on [LibreGraph Connect (lico)](https://github.com/libregraph/lico) for OpenCloud. + +It is mainly targeted at smaller installations. For larger setups it is recommended to replace IDP with an external OpenID Connect Provider. + +By default, it is configured to use the OpenCloud IDM service as its LDAP backend for looking up and authenticating users. Other backends like an external LDAP server can be configured via a set of [enviroment variables](https://docs.opencloud.eu/docs/dev/server/services/idp/environment-variables). + +Note that translations provided by the IDP service are not maintained via OpenCloud but part of the embedded [LibreGraph Connect Identifier](https://github.com/libregraph/lico/tree/master/identifier) package. + + +## Table of Contents + +* [Configuration](#configuration) + * [Custom Clients](#custom-clients) + +## Configuration + +### Custom Clients + +By default the `idp` service generates a OIDC client configuration suitable for +using OpenCloud with the standard client applications (Web, Desktop, iOS and +Android). If you need to configure additional client it is possible to inject a +custom configuration via `yaml`. This can be done by adding a section `clients` +to the `idp` section of the main configuration file (`opencloud.yaml`). This section +needs to contain configuration for all clients (including the standard clients). + +For example if you want to add a (public) client for use with the oidc-agent you would +need to add this snippet to the `idp` section in `opencloud.yaml`. + +```yaml +clients: +- id: web + name: OpenCloud Web App + trusted: true + secret: "" + redirect_uris: + - https://opencloud.k8s:9200/ + - https://opencloud.k8s:9200/oidc-callback.html + - https://opencloud.k8s:9200/oidc-silent-redirect.html + post_logout_redirect_uris: [] + origins: + - https://opencloud.k8s:9200 + application_type: "" +- id: OpenCloudDesktop + name: OpenCloud Desktop Client + trusted: false + secret: "" + redirect_uris: + - http://127.0.0.1 + - http://localhost + post_logout_redirect_uris: [] + origins: [] + application_type: native +- id: OpenCloudAndroid + name: OpenCloud Android App + trusted: false + secret: "" + redirect_uris: + - oc://android.opencloud.eu + post_logout_redirect_uris: + - oc://android.opencloud.eu + origins: [] + application_type: native +- id: OpenCloudIOS + name: OpenCloud iOS App + trusted: false + secret: "" + redirect_uris: + - oc://ios.opencloud.eu + post_logout_redirect_uris: + - oc://ios.opencloud.eu + origins: [] + application_type: native +- id: oidc-agent + name: OIDC Agent + trusted: false + secret: "" + redirect_uris: + - http://127.0.0.1 + - http://localhost + post_logout_redirect_uris: [] + origins: [] + application_type: native +``` + + + + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations.yaml new file mode 100644 index 00000000..5b61607d --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations.yaml @@ -0,0 +1,31 @@ +# Autogenerated +# Filename: invitations.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9269 + token: "" + pprof: false + zpages: false +http: + addr: 127.0.0.1:9265 + root: /graph/v1.0 + cors: + allow_origins: + - https://localhost:9200 + allow_methods: [] + allow_headers: [] + allow_credentials: false + tls: + enabled: false + cert: "" + key: "" +keycloak: + base_path: "" + client_id: "" + client_secret: "" + client_realm: "" + user_realm: "" + insecure_skip_verify: false +token_manager: + jwt_secret: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_configvars.mdx new file mode 100644 index 00000000..129434b2 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_configvars.mdx @@ -0,0 +1,25 @@ +Environment variables for the **invitations** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`INVITATIONS_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`INVITATIONS_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9269`| +|`INVITATIONS_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`INVITATIONS_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`INVITATIONS_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`INVITATIONS_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9265`| +|`INVITATIONS_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/graph/v1.0`| +|`OC_CORS_ALLOW_ORIGINS`
`INVITATIONS_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.`|`[https://localhost:9200]`| +|`OC_CORS_ALLOW_METHODS`
`INVITATIONS_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.`|`[]`| +|`OC_CORS_ALLOW_HEADERS`
`INVITATIONS_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.`|`[]`| +|`OC_CORS_ALLOW_CREDENTIALS`
`INVITATIONS_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.`|`false`| +|`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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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_KEYCLOAK_BASE_PATH`
`INVITATIONS_KEYCLOAK_BASE_PATH`| 1.0.0 |string|`The URL to access keycloak.`|``| +|`OC_KEYCLOAK_CLIENT_ID`
`INVITATIONS_KEYCLOAK_CLIENT_ID`| 1.0.0 |string|`The client ID to authenticate with keycloak.`|``| +|`OC_KEYCLOAK_CLIENT_SECRET`
`INVITATIONS_KEYCLOAK_CLIENT_SECRET`| 1.0.0 |string|`The client secret to use in authentication.`|``| +|`OC_KEYCLOAK_CLIENT_REALM`
`INVITATIONS_KEYCLOAK_CLIENT_REALM`| 1.0.0 |string|`The realm the client is defined in.`|``| +|`OC_KEYCLOAK_USER_REALM`
`INVITATIONS_KEYCLOAK_USER_REALM`| 1.0.0 |string|`The realm users are defined.`|``| +|`OC_KEYCLOAK_INSECURE_SKIP_VERIFY`
`INVITATIONS_KEYCLOAK_INSECURE_SKIP_VERIFY`| 1.0.0 |bool|`Disable TLS certificate validation for Keycloak connections. Do not set this in production environments.`|`false`| +|`OC_JWT_SECRET`
`INVITATIONS_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_readme.mdx new file mode 100755 index 00000000..9a272389 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/invitations_readme.mdx @@ -0,0 +1,68 @@ +--- +title: Invitations +date: 2026-01-15T10:35:01.391512693Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/invitations +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The invitations service provides an [Invitation Manager](https://learn.microsoft.com/en-us/graph/api/invitation-post?view=graph-rest-1.0&tabs=http) that can be used to invite external users, aka guests, to an organization. + +* Users invited via the Invitation Manager (via the libre graph API) will have the `userType="Guest"`. +* Users belonging to the organization have the `userType="Member"`. + +The corresponding CS3 API [user types](https://cs3org.github.io/cs3apis/#cs3.identity.user.v1beta1.UserType) used to reperesent this are: `USER_TYPE_GUEST` and `USER_TYPE_PRIMARY`. + + +## Table of Contents + +* [Provisioning Backends](#provisioning-backends) + * [Keycloak](#keycloak) + * [Keycloak Realm Configuration](#keycloak-realm-configuration) +* [Backend Configuration](#backend-configuration) +* [Bridging Provisioning Delay](#bridging-provisioning-delay) + +## Provisioning Backends + +When OpenCloud is used via the IDM service for the user management, users are created using the `/graph/v1.0/users` endpoint via the libre graph API. For larger deployments, the Keycloak admin API can be used to provision users. In a future step, the endpoint, credentials and body might be made configurable using templates. + +### Keycloak + +The default and currently only available backend used to handle invitations is [Keycloak](https://www.keycloak.org/). Keycloak is an open source identity and access management (IAM) system which is also integrated by other OpenCloud services as an authentication and authorization backend. + +#### Keycloak Realm Configuration + + + +See the [example configuration json file](https://github.com/opencloud-eu/opencloud/blob/main/services/invitations/md-sources/example-realm.json) of a Keycloak realm the backend will work with. This file includes the `invitations` client, which is relevant for this service. + +To use the example json, set the `INVITATIONS_KEYCLOAK_CLIENT_ID` setting to `invitations`, though any other client ID can be configured. + +Importing this example into Keycloak will give you a realm that federates with an LDAP server, has the right +clients configured and all mappers correctly set. Be sure to set all the credentials after the import, +as they will be disabled. + +The most relevant bits are the mappers for the `OPENCLOUD_ID` and `OPENCLOUD_USER_TYPE` user properties. + +## Backend Configuration + +After Keycloak has been configured, the invitation service needs to be configured with the following environment variables: + +* `INVITATIONS_KEYCLOAK_BASE_PATH`: The URL to access Keycloak. +* `INVITATIONS_KEYCLOAK_CLIENT_ID`: The client ID of the client to use. In the above example, `invitations` is used. +* `INVITATIONS_KEYCLOAK_CLIENT_SECRET`: The client secret used to authenticate. This can be found in the Keycloak UI. +* `INVITATIONS_KEYCLOAK_CLIENT_REALM`: The realm where the client was added. In the example above, `opencloud` is used. +* `INVITATIONS_KEYCLOAK_USER_REALM`: The realm where to add the users. In the example above, `opencloud` is used. +* `INVITATIONS_KEYCLOAK_INSECURE_SKIP_VERIFY`: If set to true, the verification of the Keycloak HTTPS certificate is skipped. This is not recommended in production environments. + +## Bridging Provisioning Delay + +Consider that when a guest account has to be provisioned in an external user management, there might be a delay between creating the user and the user being available in the local OpenCloud system. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats.yaml new file mode 100644 index 00000000..75c79ef2 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats.yaml @@ -0,0 +1,18 @@ +# Autogenerated +# Filename: nats.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9234 + token: "" + pprof: false + zpages: false +nats: + host: 127.0.0.1 + port: 9233 + clusterid: opencloud-cluster + store_dir: /root/.opencloud/nats + tls_cert: /root/.opencloud/nats/tls.crt + tls_key: /root/.opencloud/nats/tls.key + tls_skip_verify_client_cert: false + enable_tls: false diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_configvars.mdx new file mode 100644 index 00000000..7d3f85fc --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_configvars.mdx @@ -0,0 +1,17 @@ +Environment variables for the **nats** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`NATS_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`NATS_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9234`| +|`NATS_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`NATS_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`NATS_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`NATS_NATS_HOST`| 1.0.0 |string|`Bind address.`|`127.0.0.1`| +|`NATS_NATS_PORT`| 1.0.0 |int|`Bind port.`|`9233`| +|`NATS_NATS_CLUSTER_ID`| 1.0.0 |string|`ID of the NATS cluster.`|`opencloud-cluster`| +|`NATS_NATS_STORE_DIR`| 1.0.0 |string|`The directory where the filesystem storage will store NATS JetStream data. If not defined, the root directory derives from $OC_BASE_DATA_PATH/nats.`|`/root/.opencloud/nats`| +|`NATS_TLS_CERT`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the NATS listener. If not defined, the root directory derives from $OC_BASE_DATA_PATH/nats.`|`/root/.opencloud/nats/tls.crt`| +|`NATS_TLS_KEY`| 1.0.0 |string|`Path/File name for the TLS certificate key (in PEM format) for the NATS listener. If not defined, the root directory derives from $OC_BASE_DATA_PATH/nats.`|`/root/.opencloud/nats/tls.key`| +|`OC_INSECURE`
`NATS_TLS_SKIP_VERIFY_CLIENT_CERT`| 1.0.0 |bool|`Whether the NATS server should skip the client certificate verification during the TLS handshake.`|`false`| +|`OC_EVENTS_ENABLE_TLS`
`NATS_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`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_readme.mdx new file mode 100755 index 00000000..038cf3af --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/nats_readme.mdx @@ -0,0 +1,47 @@ +--- +title: Nats +date: 2026-01-15T10:35:01.391623313Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/nats +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The nats service is the event broker of the system. It distributes events among all other services and enables other services to communicate asynchronous. + +Services can `Publish` events to the nats service and nats will store these events on disk and distribute these events to other services eventually. Services can `Consume` events from the nats service by registering to a `ConsumerGroup`. Each `ConsumerGroup` is guaranteed to get each event exactly once. In most cases, each service will register its own `ConsumerGroup`. When there are multiple instances of a service, those instances will usually use that `ConsumerGroup` as common resource. + + +## Table of Contents + +* [Underlying Technology](#underlying-technology) +* [Default Registry](#default-registry) +* [Persistance](#persistance) +* [TLS Encryption](#tls-encryption) + +## Underlying Technology + +As the service name suggests, this service is based on [NATS](https://nats.io/) specifically on [NATS Jetstream](https://docs.nats.io/nats-concepts/jetstream) to enable persistence. + +## Default Registry + +By default, `nats-js-kv` is configured as embedded default registry via the `MICRO_REGISTRY` environment variable. If you do not want using the build-in nats registry, set `MICRO_REGISTRY_ADDRESS` to the address of the nats-js cluster, which is the same value as `OC_EVENTS_ENDPOINT`. Optionally use `MICRO_REGISTRY_AUTH_USERNAME` and `MICRO_REGISTRY_AUTH_PASSWORD` to authenticate with the external nats cluster. + +## Persistance + +To be able to deliver events even after a system or service restart, nats will store events in a folder on the local filesystem. This folder can be specified by setting the `NATS_NATS_STORE_DIR` enviroment variable. If not set, the service will fall back to `$OC_BASE_DATA_PATH/nats`. + +## TLS Encryption + +Connections to the nats service (`Publisher`/`Consumer` see above) can be TLS encrypted by setting the corresponding env vars `NATS_TLS_CERT`, `NATS_TLS_KEY` to the cert and key files and `ENABLE_TLS` to true. Checking the certificate of incoming request can be disabled with the `NATS_EVENTS_ENABLE_TLS` environment variable. + +Certificate files can also be set via global variables starting with `OC_`, for details see the environment variable list. + +Note that using TLS is highly recommended for productive environments, especially when using container orchestration with Kubernetes. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications.yaml new file mode 100644 index 00000000..cc6a0c10 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications.yaml @@ -0,0 +1,48 @@ +# Autogenerated +# Filename: notifications.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9174 + token: "" + pprof: false + zpages: false +opencloud_url: https://localhost:9200 +notifications: + SMTP: + smtp_host: "" + smtp_port: 0 + smtp_sender: "" + smtp_username: "" + smtp_password: "" + insecure: false + smtp_authentication: "" + smtp_encryption: none + events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" + email_template_path: "" + translation_path: "" + default_language: "" + reva_gateway: eu.opencloud.api.gateway + grpc_client_tls: null +grpc_client_tls: + mode: "" + cacert: "" +service_account: + service_account_id: "" + service_account_secret: "" +store: + store: nats-js-kv + nodes: + - 127.0.0.1:9233 + database: notifications + table: "" + ttl: 336h0m0s + username: "" + password: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_configvars.mdx new file mode 100644 index 00000000..e49cbe7f --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_configvars.mdx @@ -0,0 +1,40 @@ +Environment variables for the **notifications** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`NOTIFICATIONS_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`NOTIFICATIONS_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9174`| +|`NOTIFICATIONS_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`NOTIFICATIONS_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`NOTIFICATIONS_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`OC_URL`
`NOTIFICATIONS_WEB_UI_URL`| 1.0.0 |string|`The public facing URL of the OpenCloud Web UI, used e.g. when sending notification eMails`|`https://localhost:9200`| +|`NOTIFICATIONS_SMTP_HOST`| 1.0.0 |string|`SMTP host to connect to.`|``| +|`NOTIFICATIONS_SMTP_PORT`| 1.0.0 |int|`Port of the SMTP host to connect to.`|`0`| +|`NOTIFICATIONS_SMTP_SENDER`| 1.0.0 |string|`Sender address of emails that will be sent (e.g. 'OpenCloud '.`|``| +|`NOTIFICATIONS_SMTP_USERNAME`| 1.0.0 |string|`Username for the SMTP host to connect to.`|``| +|`NOTIFICATIONS_SMTP_PASSWORD`| 1.0.0 |string|`Password for the SMTP host to connect to.`|``| +|`NOTIFICATIONS_SMTP_INSECURE`| 1.0.0 |bool|`Allow insecure connections to the SMTP server.`|`false`| +|`NOTIFICATIONS_SMTP_AUTHENTICATION`| 1.0.0 |string|`Authentication method for the SMTP communication. Possible values are 'login', 'plain', 'crammd5', 'none' or 'auto'. If set to 'auto' or unset, the authentication method is automatically negotiated with the server.`|``| +|`NOTIFICATIONS_SMTP_ENCRYPTION`| 1.0.0 |string|`Encryption method for the SMTP communication. Possible values are 'starttls', 'ssltls' and 'none'.`|`none`| +|`OC_EVENTS_ENDPOINT`
`NOTIFICATIONS_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_CLUSTER`
`NOTIFICATIONS_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`NOTIFICATIONS_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`NOTIFICATIONS_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided NOTIFICATIONS_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`NOTIFICATIONS_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_AUTH_USERNAME`
`NOTIFICATIONS_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_AUTH_PASSWORD`
`NOTIFICATIONS_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_EMAIL_TEMPLATE_PATH`
`NOTIFICATIONS_EMAIL_TEMPLATE_PATH`| 1.0.0 |string|`Path to Email notification templates overriding embedded ones.`|``| +|`OC_TRANSLATION_PATH`
`NOTIFICATIONS_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_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_REVA_GATEWAY`| 1.0.0 |string|`CS3 gateway used to look up user metadata`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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_SERVICE_ACCOUNT_ID`
`NOTIFICATIONS_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`
`NOTIFICATIONS_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| +|`OC_PERSISTENT_STORE`
`NOTIFICATIONS_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_NODES`
`NOTIFICATIONS_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]`| +|`NOTIFICATIONS_STORE_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`notifications`| +|`NOTIFICATIONS_STORE_TABLE`| 1.0.0 |string|`The database table the store should use.`|``| +|`OC_PERSISTENT_STORE_TTL`
`NOTIFICATIONS_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_PERSISTENT_STORE_AUTH_USERNAME`
`NOTIFICATIONS_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_AUTH_PASSWORD`
`NOTIFICATIONS_STORE_AUTH_PASSWORD`| 1.0.0 |string|`The password to authenticate with the store. Only applies when store type 'nats-js-kv' is configured.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_readme.mdx new file mode 100755 index 00000000..8d734550 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/notifications_readme.mdx @@ -0,0 +1,130 @@ +--- +title: Notification +date: 2026-01-15T10:35:01.391763994Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/notifications +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The notification service is responsible for sending emails to users informing them about events that happened. To do this, it hooks into the event system and listens for certain events that the users need to be informed about. + + +## Table of Contents + +* [Email Notification Templates](#email-notification-templates) + * [Templates subfolder hierarchy](#templates-subfolder-hierarchy) +* [Sending Grouped Emails](#sending-grouped-emails) + * [Storing](#storing) +* [Translations](#translations) + * [Translation Rules](#translation-rules) +* [Default Language](#default-language) + +## Email Notification Templates + +The `notifications` service has embedded email text and html body templates. + +Email templates can use the placeholders `{{ .Greeting }}`, `{{ .MessageBody }}` and `{{ .CallToAction }}` which are replaced with translations when sent, see the [Translations](#translations) section for more details. Though the email subject is also part of translations, it has no placeholder as it is a mandatory email component. + +Depending on the email purpose, placeholders will contain different strings. An individual translatable string is available for each purpose, finally resolved by the placeholder. The embedded templates are available for all deployment scenarios. + +```text +template + placeholders + translated strings <-- source strings <-- purpose +final output +``` + +In addition, the notifications service supports custom templates. Custom email templates take precedence over the embedded ones. If a custom email template exists, the embedded templates are not used. To configure custom email templates, the `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` environment variable needs to point to a base folder that will contain the email templates and follow the [templates subfolder hierarchy](#templates-subfolder-hierarchy).This path must be available from all instances of the notifications service, a shared storage is recommended. +```text +{NOTIFICATIONS_EMAIL_TEMPLATE_PATH}/templates/text/email.text.tmpl +{NOTIFICATIONS_EMAIL_TEMPLATE_PATH}/templates/html/email.html.tmpl +{NOTIFICATIONS_EMAIL_TEMPLATE_PATH}/templates/html/img/ +``` +The source templates provided by OpenCloud you can derive from are located in the following base folder [https://github.com/opencloud-eu/opencloud/tree/main/services/notifications/pkg/email/templates](https://github.com/opencloud-eu/opencloud/tree/main/services/notifications/pkg/email/templates) with subfolders `templates/text` and `templates/html`. + +- [text/email.text.tmpl](https://github.com/opencloud-eu/opencloud/blob/main/services/notifications/pkg/email/templates/text/email.text.tmpl) +- [html/email.html.tmpl](https://github.com/opencloud-eu/opencloud/blob/main/services/notifications/pkg/email/templates/html/email.html.tmpl) + +### Templates subfolder hierarchy +```text +templates +│ +└───html +│ │ email.html.tmpl +│ │ +│ └───img +│ │ logo-mail.gif +│ +└───text + │ email.text.tmpl +``` + +Custom email templates referenced via `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` must also be located in subfolder `templates/text` and `templates/html` and must have the same names as the embedded templates. It is important that the names of these files and folders match the embedded ones. +The `templates/html` subfolder contains a default HTML template provided by OpenCloud. When using a custom HTML template, hosted images can either be linked with standard HTML code like ```logo-mail``` or embedded as a CID source ```logo-mail```. In the latter case, image files must be located in the `templates/html/img` subfolder. Supported embedded image types are png, jpeg, and gif. +Consider that embedding images via a CID resource may not be fully supported in all email web clients. + +## Sending Grouped Emails + +The `notification` service can initiate sending emails based on events stored in the configured store that are grouped into a `daily` or `weekly` bucket. These groups contain events that get populated e.g. when the user configures `daily` or `weekly` email notifications in his personal settings in the web UI. If a user does not define any of the named groups for notification events, no event is stored. + +Grouped events are stored for the TTL defined in `OC_PERSISTENT_STORE_TTL`. This TTL can either be configured globally or individually for the notification service via the `NOTIFICATIONS_STORE_TTL` envvar. + +Grouped events that have passed the TTL are removed automatically without further notice or sending! + +To initiate sending grouped emails like via a cron job, use the `opencloud notifications send-email` command. Note that the command mandatory requires at least one option which is `--daily` or `--weekly`. Note that both options can be used together. + +### Storing + +The `notifications` service persists information via the configured store in `NOTIFICATIONS_STORE`. Possible stores are: +- `memory`: Basic in-memory store. Will not survive a restart. This is not recommended for this service. +- `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. +- `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store). This is the default value. +- `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: +- When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. +- When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. +- When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + +## Translations + +The `notifications` service has embedded translations sourced via transifex to provide a basic set of translated languages. These embedded translations are available for all deployment scenarios. + +In addition, the service supports custom translations, though it is currently not possible to just add custom translations to embedded ones. If custom translations are configured, the embedded ones are not used. To configure custom translations, +the `NOTIFICATIONS_TRANSLATION_PATH` environment variable needs to point to a base folder that will contain the translation files. This path must be available from all instances of the notifications service, a shared storage is recommended. Translation files must be of type [.po](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html#PO-Files) or [.mo](https://www.gnu.org/software/gettext/manual/html_node/Binaries.html). For each language, the filename needs to be `notifications.po` (or `notifications.mo`) and stored in a folder structure defining the language code. In general the path/name pattern for a translation file needs to be: + +```text +{NOTIFICATIONS_TRANSLATION_PATH}/{language-code}/LC_MESSAGES/notifications.po +``` + +The language code pattern is composed of `language[_territory]` where `language` is the base language and `_territory` is optional and defines a country. + +For example, for the language `de`, one needs to place the corresponding translation files to `{NOTIFICATIONS_TRANSLATION_PATH}/de/LC_MESSAGES/notifications.po`. + + + +Important: For the time being, the embedded OpenCloud Web frontend only supports the main language code but does not handle any territory. When strings are available in the language code `language_territory`, the web frontend does not see it as it only requests `language`. In consequence, any translations made must exist in the requested `language` to avoid a fallback to the default. + +### Translation Rules + +* If a requested language code is not available, the service tries to fall back to the base language if available. For example, if the requested language-code `de_DE` is not available, the service tries to fall back to translations in the `de` folder. +* If the base language `de` is also not available, the service falls back to the system's default English (`en`), +which is the source of the texts provided by the code. + +## Default Language + +The default language can be defined via the `OC_DEFAULT_LANGUAGE` environment variable. See the `settings` service for a detailed description. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm.yaml new file mode 100644 index 00000000..bb938d87 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm.yaml @@ -0,0 +1,109 @@ +# Autogenerated +# Filename: ocm.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9281 + token: "" + pprof: false + zpages: false +http: + addr: 127.0.0.1:9280 + protocol: tcp + prefix: "" + cors: + allow_origins: + - https://localhost:9200 + allow_methods: + - OPTIONS + - HEAD + - GET + - PUT + - POST + - DELETE + - MKCOL + - PROPFIND + - PROPPATCH + - MOVE + - COPY + - REPORT + - SEARCH + allow_headers: + - Origin + - Accept + - Content-Type + - Depth + - Authorization + - Ocs-Apirequest + - If-None-Match + - If-Match + - Destination + - Overwrite + - X-Request-Id + - X-Requested-With + - Tus-Resumable + - Tus-Checksum-Algorithm + - Upload-Concat + - Upload-Length + - Upload-Metadata + - Upload-Defer-Length + - Upload-Expires + - Upload-Checksum + - Upload-Offset + - X-HTTP-Method-Override + - Cache-Control + allow_credentials: false +middleware: + auth: + credentials_by_user_agent: {} +grpc: + addr: 127.0.0.1:9282 + tls: null + protocol: "" +grpc_client_tls: null +service_account: + service_account_id: "" + service_account_secret: "" +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +ocmd: + prefix: ocm + expose_recipient_display_name: false +sciencemesh: + prefix: sciencemesh + science_mesh_directory_url: "" + directory_service_urls: "" + invite_accept_dialog: /open-cloud-mesh/accept-invite +ocm_invite_manager: + driver: json + drivers: + json: + file: /root/.opencloud/storage/ocm/ocminvites.json + token_expiration: 24h0m0s + timeout: 30s + insecure: false +ocm_provider_authorizer_driver: json +ocm_provider_authorizer_drivers: + json: + providers: /root/.opencloud/config/ocmproviders.json +ocm_share_provider: + driver: json + drivers: + json: + file: /root/.opencloud/storage/ocm/ocmshares.json + insecure: false + webapp_template: "" +ocm_core: + driver: json + drivers: + json: + file: /root/.opencloud/storage/ocm/ocmshares.json +ocm_storage_provider: + insecure: false + storage_root: /root/.opencloud/storage/ocm + data_server_url: http://localhost:9280/data diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_configvars.mdx new file mode 100644 index 00000000..23efe28a --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_configvars.mdx @@ -0,0 +1,53 @@ +Environment variables for the **ocm** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`OCM_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`OCM_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9281`| +|`OCM_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`OCM_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`OCM_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`OCM_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9280`| +|`OCM_HTTP_PROTOCOL`| 1.0.0 |string|`The transport protocol of the HTTP service.`|`tcp`| +|`OCM_HTTP_PREFIX`| 1.0.0 |string|`The path prefix where OCM can be accessed (defaults to /).`|``| +|`OC_CORS_ALLOW_ORIGINS`
`OCM_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.`|`[https://localhost:9200]`| +|`OC_CORS_ALLOW_METHODS`
`OCM_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.`|`[OPTIONS HEAD GET PUT POST DELETE MKCOL PROPFIND PROPPATCH MOVE COPY REPORT SEARCH]`| +|`OC_CORS_ALLOW_HEADERS`
`OCM_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.`|`[Origin Accept Content-Type Depth Authorization Ocs-Apirequest If-None-Match If-Match Destination Overwrite X-Request-Id X-Requested-With Tus-Resumable Tus-Checksum-Algorithm Upload-Concat Upload-Length Upload-Metadata Upload-Defer-Length Upload-Expires Upload-Checksum Upload-Offset X-HTTP-Method-Override Cache-Control]`| +|`OC_CORS_ALLOW_CREDENTIALS`
`OCM_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.`|`false`| +|`OCM_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9282`| +|`OC_GRPC_PROTOCOL`
`OCM_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|``| +|`OC_SERVICE_ACCOUNT_ID`
`OCM_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`
`OCM_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| +|`OC_EVENTS_ENDPOINT`
`OCM_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_CLUSTER`
`OCM_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`OCM_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`OCM_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided OCM_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`OCM_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_AUTH_USERNAME`
`OCM_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_AUTH_PASSWORD`
`OCM_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_JWT_SECRET`
`OCM_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`OCM_OCMD_PREFIX`| 1.0.0 |string|`URL path prefix for the OCMD service. Note that the string must not start with '/'.`|`ocm`| +|`OCM_OCMD_EXPOSE_RECIPIENT_DISPLAY_NAME`| 1.0.0 |bool|`Expose the display name of OCM share recipients.`|`false`| +|`OCM_SCIENCEMESH_PREFIX`| 1.0.0 |string|`URL path prefix for the ScienceMesh service. Note that the string must not start with '/'.`|`sciencemesh`| +|`OCM_MESH_DIRECTORY_URL`| 1.0.0 |string|`URL of the mesh directory service.`|``| +|`OCM_DIRECTORY_SERVICE_URLS`| 3.5.0 |string|`Space delimited URLs of the directory services.`|``| +|`OCM_INVITE_ACCEPT_DIALOG`| 3.5.0 |string|`/open-cloud-mesh/accept-invite;The frontend URL where to land when receiving an invitation`|`/open-cloud-mesh/accept-invite`| +|`OCM_OCM_INVITE_MANAGER_DRIVER`| 1.0.0 |string|`Driver to be used to persist OCM invites. Supported value is only 'json'.`|`json`| +|`OCM_OCM_INVITE_MANAGER_JSON_FILE`| 1.0.0 |string|`Path to the JSON file where OCM invite data will be stored. This file is maintained by the instance and must not be changed manually. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage/ocm.`|`/root/.opencloud/storage/ocm/ocminvites.json`| +|`OCM_OCM_INVITE_MANAGER_TOKEN_EXPIRATION`| 1.0.0 |Duration|`Expiry duration for invite tokens.`|`24h0m0s`| +|`OCM_OCM_INVITE_MANAGER_TIMEOUT`| 1.0.0 |Duration|`Timeout specifies a time limit for requests made to OCM endpoints.`|`30s`| +|`OCM_OCM_INVITE_MANAGER_INSECURE`| 1.0.0 |bool|`Disable TLS certificate validation for the OCM connections. Do not set this in production environments.`|`false`| +|`SHARING_OCM_PROVIDER_AUTHORIZER_DRIVER`| 1.0.0 |string|`Driver to be used to persist ocm invites. Supported value is only 'json'.`|`json`| +|`OCM_OCM_PROVIDER_AUTHORIZER_PROVIDERS_FILE`| 1.0.0 |string|`Path to the JSON file where ocm invite data will be stored. Defaults to $OC_CONFIG_DIR/ocmproviders.json.`|`/root/.opencloud/config/ocmproviders.json`| +|`OCM_OCM_SHARE_PROVIDER_DRIVER`| 1.0.0 |string|`Driver to be used for the OCM share provider. Supported value is only 'json'.`|`json`| +|`OCM_OCM_SHAREPROVIDER_JSON_FILE`| 1.0.0 |string|`Path to the JSON file where OCM share data will be stored. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage.`|`/root/.opencloud/storage/ocm/ocmshares.json`| +|`OCM_OCM_SHARE_PROVIDER_INSECURE`| 1.0.0 |bool|`Disable TLS certificate validation for the OCM connections. Do not set this in production environments.`|`false`| +|`OCM_WEBAPP_TEMPLATE`| 1.0.0 |string|`Template for the webapp url.`|``| +|`OCM_OCM_CORE_DRIVER`| 1.0.0 |string|`Driver to be used for the OCM core. Supported value is only 'json'.`|`json`| +|`OCM_OCM_CORE_JSON_FILE`| 1.0.0 |string|`Path to the JSON file where OCM share data will be stored. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage.`|`/root/.opencloud/storage/ocm/ocmshares.json`| +|`OCM_OCM_STORAGE_PROVIDER_INSECURE`| 1.0.0 |bool|`Disable TLS certificate validation for the OCM connections. Do not set this in production environments.`|`false`| +|`OCM_OCM_STORAGE_PROVIDER_STORAGE_ROOT`| 1.0.0 |string|`Directory where the ocm storage provider persists its data like tus upload info files.`|`/root/.opencloud/storage/ocm`| +|`OCM_OCM_STORAGE_DATA_SERVER_URL`| 1.0.0 |string|`URL of the data server, needs to be reachable by the data gateway provided by the frontend service or the user if directly exposed.`|`http://localhost:9280/data`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_readme.mdx new file mode 100755 index 00000000..0e0de444 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocm_readme.mdx @@ -0,0 +1,154 @@ +--- +title: OCM +date: 2026-01-15T10:35:01.391919943Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/ocm +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `ocm` service provides federated sharing functionality based on the [sciencemesh](https://sciencemesh.io/) and [ocm](https://github.com/cs3org/OCM-API) HTTP APIs. Internally the `ocm` service consists of the following services and endpoints: + +External HTTP APIs: +* sciencemesh: serves the API for the invitation workflow +* ocmd: serves the API for managing federated shares + +Internal GRPC APIs: +* ocmproviderauthorizer: manages the list of trusted providers and verifies requests +* ocminvitemanager: manages the list and state of invite tokens +* ocmshareprovider: manages ocm shares on the sharer +* ocmcore: used for creating federated shares on the receiver side +* authprovider: authenticates webdav requests using the ocm share tokens + + +## Table of Contents + +* [Enable OCM](#enable-ocm) +* [Trust Between Instances](#trust-between-instances) +* [Invitation Workflow](#invitation-workflow) +* [Creating Shares](#creating-shares) + +## Enable OCM + +To enable OpenCloudMesh, you have to set the following environment variable. + +```console +OC_ENABLE_OCM=true +``` + +## Trust Between Instances + +The `ocm` services implements an invitation workflow which needs to be followed before creating federated shares. Invitations are limited to trusted instances, however. + +The list of trusted instances is managed by the `ocmproviderauthorizer` service. The only supported backend currently is `json` which stores the list in a json file on disk. Note that the `ocmproviders.json` file, which holds that configuration, is expected to be located in the root of the OpenCloud config directory if not otherwise defined. See the `OCM_OCM_PROVIDER_AUTHORIZER_PROVIDERS_FILE` envvar for more details. + +When all instances of a federation should trust each other, an `ocmproviders.json` file like this can be used for all instances: +```json +[ + { + "name": "OpenCloud Test 1", + "full_name": "OpenCloud Test provider 1", + "organization": "OpenCloud One", + "domain": "cloud1.opencloud.test", + "homepage": "https://cloud1.opencloud.test", + "description": "First OpenCloud Example cloud storage", + "services": [ + { + "endpoint": { + "type": { + "name": "OCM", + "description": "cloud1.opencloud.test Open Cloud Mesh API" + }, + "name": "cloud1.opencloud.test - OCM API", + "path": "https://cloud1.opencloud.test/ocm/", + "is_monitored": true + }, + "api_version": "0.0.1", + "host": "http://cloud1.opencloud.test" + }, + { + "endpoint": { + "type": { + "name": "Webdav", + "description": "cloud1.opencloud.test Webdav API" + }, + "name": "cloud1.opencloud.test Example - Webdav API", + "path": "https://cloud1.opencloud.test/dav/", + "is_monitored": true + }, + "api_version": "0.0.1", + "host": "https://cloud1.opencloud.test/" + } + ] + }, + { + "name": "OpenCloud Test 2", + "full_name": "OpenCloud Test provider 2", + "organization": "OpenCloud Two", + "domain": "cloud2.opencloud.test", + "homepage": "https://cloud2.opencloud.test", + "description": "Second OpenCloud Example cloud storage", + "services": [ + { + "endpoint": { + "type": { + "name": "OCM", + "description": "cloud2.opencloud.test Open Cloud Mesh API" + }, + "name": "cloud2.opencloud.test - OCM API", + "path": "https://cloud2.opencloud.test/ocm/", + "is_monitored": true + }, + "api_version": "0.0.1", + "host": "http://cloud2.opencloud.test" + }, + { + "endpoint": { + "type": { + "name": "Webdav", + "description": "cloud2.opencloud.test Webdav API" + }, + "name": "cloud2.opencloud.test Example - Webdav API", + "path": "https://cloud2.opencloud.test/dav/", + "is_monitored": true + }, + "api_version": "0.0.1", + "host": "https://cloud2.opencloud.test/" + } + ] + } +] +``` + +:::info +Note: the `domain` must not contain the protocol as it has to match the [GOCDB site object domain](https://developer.sciencemesh.io/docs/technical-documentation/central-database/#site-object). +::: + +The above federation consists of two instances: `cloud1.opencloud.test` and `cloud2.opencloud.test` that can use the Invitation workflow described below to generate, send and accept invitations. + +## Invitation Workflow + +Before sharing a resource with a remote user this user has to be invited by the sharer. + +In order to do so a POST request is sent to the `generate-invite` endpoint of the sciencemesh API. The generated token is passed on to the receiver, who will then use the `accept-invite` endpoint to accept the invitation. As a result remote users will be added to the `ocminvitemanager` on both sides. See [invitation flow](invitation-flow) for the according sequence diagram. + +The data backend of the `ocminvitemanager` is configurable. The only supported backend currently is `json` which stores the data in a json file on disk. + +## Creating Shares + +:::info +The below info is outdated as we allow creating federated shares using the graph API. Clients can now discover the available sharing roles and invite federated users using the graph API. +::: + +OCM Shares are currently created using the ocs API, just like regular shares. The difference is the share type, which is 6 (ShareTypeFederatedCloudShare) in this case, and a few additional parameters required for identifying the remote user. + +See [Create share flow](create-share-flow) for the according sequence diagram. + +The data backends of the `ocmshareprovider` and `ocmcore` services are configurable. The only supported backend currently is `json` which stores the data in a json file on disk. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs.yaml new file mode 100644 index 00000000..a91a765f --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs.yaml @@ -0,0 +1,45 @@ +# Autogenerated +# Filename: ocs.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9114 + token: "" + pprof: false + zpages: false +http: + addr: 127.0.0.1:9110 + root: /ocs + cors: + allow_origins: + - '*' + allow_methods: + - GET + - POST + - PUT + - PATCH + - DELETE + - OPTIONS + allow_headers: + - Authorization + - Origin + - Content-Type + - Accept + - X-Requested-With + - X-Request-Id + - Cache-Control + allow_credentials: true + tls: + enabled: false + cert: "" + key: "" +grpc_client_tls: null +signing_keys: + store: nats-js-kv + addresses: + - 127.0.0.1:9233 + ttl: 12h0m0s + username: "" + password: "" +token_manager: + jwt_secret: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_configvars.mdx new file mode 100644 index 00000000..64367371 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_configvars.mdx @@ -0,0 +1,24 @@ +Environment variables for the **ocs** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`OCS_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`OCS_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9114`| +|`OCS_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`OCS_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`OCS_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`OCS_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9110`| +|`OCS_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/ocs`| +|`OC_CORS_ALLOW_ORIGINS`
`OCS_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_CORS_ALLOW_METHODS`
`OCS_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`
`OCS_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 Cache-Control]`| +|`OC_CORS_ALLOW_CREDENTIALS`
`OCS_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_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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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_CACHE_STORE`
`OCS_PRESIGNEDURL_SIGNING_KEYS_STORE`| 1.0.0 |string|`The type of the signing key store. Supported values are: 'redis-sentinel' and 'nats-js-kv'. See the text description for details.`|`nats-js-kv`| +|`OC_CACHE_STORE_NODES`
`OCS_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES`| 1.0.0 |[]string|`A list of nodes to access the configured store. 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_TTL`
`OCS_PRESIGNEDURL_SIGNING_KEYS_STORE_TTL`| 1.0.0 |Duration|`Default time to live for signing keys. See the Environment Variable Types description for more details.`|`12h0m0s`| +|`OC_CACHE_AUTH_USERNAME`
`OCS_PRESIGNEDURL_SIGNING_KEYS_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_CACHE_AUTH_PASSWORD`
`OCS_PRESIGNEDURL_SIGNING_KEYS_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_JWT_SECRET`
`OCS_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_readme.mdx new file mode 100755 index 00000000..f158431b --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/ocs_readme.mdx @@ -0,0 +1,44 @@ +--- +title: OCS Service +date: 2026-01-15T10:35:01.392050453Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/ocs +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `ocs` service (open collaboration services) serves one purpose: it has an endpoint for signing keys which the web frontend accesses when uploading data. + + +## Table of Contents + +* [Signing-Keys Endpoint](#signing-keys-endpoint) +* [Signing-Keys Store](#signing-keys-store) + +## Signing-Keys Endpoint + +The `ocs` service contains an endpoint `/cloud/user/signing-key` on which a user can GET a signing key. Note, this functionality might be deprecated or moved in the future. + +## Signing-Keys Store + +To authenticate presigned URLs the proxy service needs to read the signing keys from a store that is populated by the ocs service. +Possible stores that can be configured via `OCS_PRESIGNEDURL_SIGNING_KEYS_STORE` are: + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `opencloudstoreservice`: Stores data in the legacy OpenCloud store service. Requires setting `OCS_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES` to `eu.opencloud.api.store`. + +The `memory` store cannot be used as it does not share the memory from the ocs service signing key memory store, even in a single process. + +Make sure to configure the same store in the proxy service. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OCS_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES` to the same value as `OCS_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES`. That way the proxy uses the same nats instance as the ocs service. + - When using `opencloudstoreservice` the `OCS_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES` must be set to the service name `eu.opencloud.api.store`. It does not support TTL and stores the presigning keys indefinitely. Also, the store service needs to be started. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies.yaml new file mode 100644 index 00000000..3f29546c --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies.yaml @@ -0,0 +1,27 @@ +# Autogenerated +# Filename: policies.yaml + +grpc: + addr: 127.0.0.1:9125 + tls: null +debug: + addr: 127.0.0.1:9129 + token: "" + pprof: false + zpages: false +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" +grpc_client_tls: null +loglevel: error +engine: + timeout: 10s + policies: [] + mimes: "" +postprocessing: + query: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_configvars.mdx new file mode 100644 index 00000000..a2db9872 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_configvars.mdx @@ -0,0 +1,20 @@ +Environment variables for the **policies** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`POLICIES_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9125`| +|`POLICIES_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9129`| +|`POLICIES_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`POLICIES_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`POLICIES_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`OC_EVENTS_ENDPOINT`
`POLICIES_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_CLUSTER`
`POLICIES_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`POLICIES_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether the server should skip the client certificate verification during the TLS handshake.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`POLICIES_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided POLICIES_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`POLICIES_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_AUTH_USERNAME`
`POLICIES_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_AUTH_PASSWORD`
`POLICIES_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_LOG_LEVEL`
`POLICIES_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`POLICIES_ENGINE_TIMEOUT`| 1.0.0 |Duration|`Sets the timeout the rego expression evaluation can take. Rules default to deny if the timeout was reached. See the Environment Variable Types description for more details.`|`10s`| +|`POLICIES_ENGINE_MIMES`| 1.0.0 |string|`Sets the mimes file path which maps mimetypes to associated file extensions. See the text description for details.`|``| +|`POLICIES_POSTPROCESSING_QUERY`| 1.0.0 |string|`Defines the 'Complete Rules' variable defined in the rego rule set this step uses for its evaluation. Defaults to deny if the variable was not found.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_readme.mdx new file mode 100755 index 00000000..02e025bb --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/policies_readme.mdx @@ -0,0 +1,197 @@ +--- +title: Policies +date: 2026-01-15T10:35:01.392180373Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/policies +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## 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. + +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 + +* [General Information](#general-information) +* [Modules](#modules) + * [gRPC API](#grpc-api) + * [Proxy Middleware](#proxy-middleware) + * [Event Service (Postprocessing)](#event-service-(postprocessing)) +* [Defining Policies to Evaluate](#defining-policies-to-evaluate) +* [Setting the Query Configuration](#setting-the-query-configuration) + * [Proxy](#proxy) + * [Postprocessing](#postprocessing) +* [Rego Key Match](#rego-key-match) +* [Extend Mimetype File Extension Mapping](#extend-mimetype-file-extension-mapping) +* [Example Policies](#example-policies) + +## General Information + +The policies service consists of the following modules: + +* 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` + +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. + +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. + +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. + +For configuration examples, the [Example Policies](#example-policies) from below are used. + +## Modules + +### 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. + +### 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. + +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" + } + } +} +``` + +### 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. + +## 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. + +If this is done, it's required to configure the policies service to use these files: + +NOTE: It is important that *all* necessary files are added to the list of files the policies service uses. + +```yaml +policies: + engine: + policies: + - your_path_to_policies/proxy.rego + - your_path_to_policies/postprocessing.rego + - 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. + +## Setting the Query Configuration + +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 `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 ``. + +### Proxy + +Note that this setting has to be part of the proxy configuration. + +```yaml +proxy: + policies_middleware: + query: data.proxy.granted +``` + +The same can be achieved by setting the following environment variable: + +```shell +export PROXY_POLICIES_QUERY=data.proxy.granted +``` + +### Postprocessing + +```yaml +policies: + postprocessing: + query: data.postprocessing.granted +``` + +The same can be achieved by setting the following environment variable: + +```shell +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: + +```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. + +## 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. + +## 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")`. + +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. + +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 +``` + +```yaml +policies: + engine: + 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). + +## 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. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing.yaml new file mode 100644 index 00000000..521a3d05 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing.yaml @@ -0,0 +1,34 @@ +# Autogenerated +# Filename: postprocessing.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9255 + token: "" + pprof: false + zpages: false +store: + store: nats-js-kv + nodes: + - 127.0.0.1:9233 + database: postprocessing + table: "" + ttl: 0s + username: "" + password: "" +postprocessing: + events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" + max_ack_pending: 10000 + ack_wait: 1m0s + workers: 3 + steps: [] + delayprocessing: 0s + retry_backoff_duration: 5s + max_retries: 14 diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_configvars.mdx new file mode 100644 index 00000000..3f3e83f3 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_configvars.mdx @@ -0,0 +1,30 @@ +Environment variables for the **postprocessing** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`POSTPROCESSING_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`POSTPROCESSING_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9255`| +|`POSTPROCESSING_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`POSTPROCESSING_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`POSTPROCESSING_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`OC_PERSISTENT_STORE`
`POSTPROCESSING_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_NODES`
`POSTPROCESSING_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]`| +|`POSTPROCESSING_STORE_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`postprocessing`| +|`POSTPROCESSING_STORE_TABLE`| 1.0.0 |string|`The database table the store should use.`|``| +|`OC_PERSISTENT_STORE_TTL`
`POSTPROCESSING_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_PERSISTENT_STORE_AUTH_USERNAME`
`POSTPROCESSING_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_AUTH_PASSWORD`
`POSTPROCESSING_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_EVENTS_ENDPOINT`
`POSTPROCESSING_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_CLUSTER`
`POSTPROCESSING_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`POSTPROCESSING_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`
`POSTPROCESSING_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_EVENTS_ENABLE_TLS`
`POSTPROCESSING_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_AUTH_USERNAME`
`POSTPROCESSING_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_AUTH_PASSWORD`
`POSTPROCESSING_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.`|``| +|`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`| +|`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`| +|`POSTPROCESSING_WORKERS`| 1.0.0 |int|`The number of concurrent go routines that fetch events from the event queue.`|`3`| +|`POSTPROCESSING_STEPS`| 1.0.0 |[]string|`A list of postprocessing steps processed in order of their appearance. Currently supported values by the system are: 'virusscan', 'policies' and 'delay'. Custom steps are allowed. See the documentation for instructions. See the Environment Variable Types description for more details.`|`[]`| +|`POSTPROCESSING_DELAY`| 1.0.0 |Duration|`After uploading a file but before making it available for download, a delay step can be added. Intended for developing purposes only. If a duration is set but the keyword 'delay' is not explicitely added to 'POSTPROCESSING_STEPS', the delay step will be processed as last step. In such a case, a log entry will be written on service startup to remind the admin about that situation. See the Environment Variable Types description for more details.`|`0s`| +|`POSTPROCESSING_RETRY_BACKOFF_DURATION`| 1.0.0 |Duration|`The base for the exponential backoff duration before retrying a failed postprocessing step. See the Environment Variable Types description for more details.`|`5s`| +|`POSTPROCESSING_MAX_RETRIES`| 1.0.0 |int|`The maximum number of retries for a failed postprocessing step.`|`14`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_readme.mdx new file mode 100755 index 00000000..fb405491 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/postprocessing_readme.mdx @@ -0,0 +1,166 @@ +--- +title: Postprocessing +date: 2026-01-15T10:35:01.392376532Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/postprocessing +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `postprocessing` service handles the coordination of asynchronous postprocessing steps. + + +## Table of Contents + +* [General Prerequisites](#general-prerequisites) +* [Postprocessing Functionality](#postprocessing-functionality) +* [Storing Postprocessing Data](#storing-postprocessing-data) +* [Additional Prerequisites for the Postprocessing Service](#additional-prerequisites-for-the-postprocessing-service) +* [Postprocessing Steps](#postprocessing-steps) + * [Virus Scanning](#virus-scanning) + * [Delay](#delay) + * [Custom Postprocessing Steps](#custom-postprocessing-steps) + * [Prerequisites](#prerequisites) + * [Workflow](#workflow) +* [CLI Commands](#cli-commands) + * [Resume Postprocessing](#resume-postprocessing) +* [Metrics](#metrics) + +## General Prerequisites + +To use the postprocessing service, an event system needs to be configured for all services. By default, `OpenCloud` ships with a preconfigured `nats` service. + +## Postprocessing Functionality + +The storageprovider service (`storage-users`) can be configured to initiate asynchronous postprocessing by setting the `OC_ASYNC_UPLOADS` environment variable to `true`. If this is the case, postprocessing will get initiated *after* uploading a file and all bytes have been received. + +The `postprocessing` service will then coordinate configured postprocessing steps like scanning the file for viruses. During postprocessing, the file will be in a `processing state` where only a limited set of actions are available. Note that this processing state excludes file accessibility by users. + +When all postprocessing steps have completed successfully, the file will be made accessible for users. + +## Storing Postprocessing Data + +The `postprocessing` service needs to store some metadata about uploads to be able to orchestrate post-processing. When running in single binary mode, the default in-memory implementation will be just fine. In distributed deployments it is recommended to use a persistent store, see below for more details. + +The `postprocessing` service stores its metadata via the configured store in `POSTPROCESSING_STORE`. Possible stores are: + - `memory`: Basic in-memory store and the default. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + +## Additional Prerequisites for the Postprocessing Service + +When postprocessing has been enabled, configuring any postprocessing step will require the requested services to be enabled and pre-configured. For example, to use the `virusscan` step, one needs to have an enabled and configured `antivirus` service. + +## Postprocessing Steps + +The postporcessing service is individually configurable. This is achieved by allowing a list of postprocessing steps that are processed in order of their appearance in the `POSTPROCESSING_STEPS` envvar. This envvar expects a comma separated list of steps that will be executed. Currently known steps to the system are `virusscan` and `delay`. Custom steps can be added but need an existing target for processing. + +### Virus Scanning + +To enable virus scanning as a postprocessing step after uploading a file, the environment variable `POSTPROCESSING_STEPS` needs to contain the word `virusscan` at one location in the list of steps. As a result, each uploaded file gets virus scanned as part of the postprocessing steps. Note that the `antivirus` service is required to be enabled and configured for this to work. + +### Delay + +Though this is for development purposes only and NOT RECOMMENDED on production systems, setting the environment variable `POSTPROCESSING_DELAY` to a duration not equal to zero will add a delay step with the configured amount of time. OpenCloud will continue postprocessing the file after the configured delay. Use the environment variable `POSTPROCESSING_STEPS` and the keyword `delay` if you have multiple postprocessing steps and want to define their order. If `POSTPROCESSING_DELAY` is set but the keyword `delay` is not contained in `POSTPROCESSING_STEPS`, it will be processed as last postprocessing step without being listed there. In this case, a log entry will be written on service startup to notify the admin about that situation. That log entry can be avoided by adding the keyword `delay` to `POSTPROCESSING_STEPS`. + +### Custom Postprocessing Steps +By using the envvar `POSTPROCESSING_STEPS`, custom postprocessing steps can be added. Any word can be used as step name but be careful not to conflict with exising keywords like `virusscan` and `delay`. In addition, if a keyword is misspelled or the corresponding service does either not exist or does not follow the necessary event communication, the postprocessing service will wait forever getting the required response to proceed and does not continue any other processing. + +#### Prerequisites +For using custom postprocessing steps you need a custom service listening to the configured event system (see `General Prerequisites`) + +#### Workflow +When defining a custom postprocessing step (eg. `"customstep"`), the postprocessing service will eventually send an event during postprocessing. The event will be of type `StartPostprocessingStep` with its field `StepToStart` set to `"customstep"`. When the service defined as custom step receives this event, it can safely execute its actions. The postprocessing service will wait until it has finished its work. The event contains further information (filename, executing user, size, ...) and also requires tokens and URLs to download the file in case byte inspection is necessary. + +Once the service defined as custom step has finished its work, it should send an event of type `PostprocessingFinished` via the configured events system back to the postprocessing service. This event needs to contain a `FinishedStep` field set to `"customstep"`. It also must contain the outcome of the step, which can be one of the following: + +- `delete`: Abort postprocessing, delete the file. +- `abort`: Abort postprocessing, keep the file. +- `retry`: There was a problem that was most likely temporary and may be solved by trying again after some backoff duration. Retry runs automatically and is defined by the backoff behavior as described below. +- `continue`: Continue postprocessing, this is the success case. + +The backoff behavior as mentioned in the `retry` outcome can be configured using the `POSTPROCESSING_RETRY_BACKOFF_DURATION` and `POSTPROCESSING_MAX_RETRIES` environment variables. The backoff duration is calculated using the following formula after each failure: `backoff_duration = POSTPROCESSING_RETRY_BACKOFF_DURATION * 2^(number of failures - 1)`. This means that the time between the next round grows exponentially limited by the number of retries. Steps that still don't succeed after the maximum number of retries will be automatically moved to the `abort` state. + +See the [cs3 org](https://github.com/cs3org/reva/blob/edge/pkg/events/postprocessing.go) for up-to-date information of reserved step names and event definitions. + +## CLI Commands + +### Resume Postprocessing + +**IMPORTANT** +> If not noted otherwise, commands with the `restart` option can also use the `resume` option. This changes behaviour slightly. +> +> * `restart`\ +> When restarting an upload, all steps for open items will be restarted, except if otherwise defined. +> * `resume`\ +> When resuming an upload, processing will continue unfinished items from their last completed step. + +If post-processing fails in one step due to an unforeseen error, current uploads will not be resumed automatically. A system administrator can instead run CLI commands to resume the failed upload manually which is at minimum a two step process. + +For details on the `storage-users` command see the **Manage Unfinished Uploads** documentation in the `storage-users` service documentation. + +Depending if you want to restart/resume all or defined failed uploads, different commands are used. + +- First, list ongoing upload sessions to identify possibly failed ones.\ + Note that there never can be a clear identification of a failed upload session due to various reasons causing them. You need to apply more critera like free space on disk, a failed service like antivirus etc. to declare an upload as failed. + + ```bash + opencloud storage-users uploads sessions + ``` + +- **All failed uploads**\ + If you want to restart/resume all failed uploads, just rerun the command with the relevant flag. Note that this is the preferred command to handle failed processing steps: + ```bash + opencloud storage-users uploads sessions --resume + ``` + +- **Particular failed uploads**\ + Use the `postprocessing` command to resume defined failed uploads. For postprocessing steps, the default is to resume . Note that at the moment, `resume` is an alias for `restart` to keep old functionality. `restart` is subject of change and will most likely be removed in a later version. + + - **Defined by ID**\ + If you want to resume only a specific upload, use the postprocessing resume command with the ID selected: + ```bash + opencloud postprocessing resume -u + ``` + + - **Defined by step**\ + Alternatively, instead of restarting one specific upload, a system admin can also resume all uploads that are currently in a specific step.\ + Examples:\ + ```bash + opencloud postprocessing resume # Resumes all uploads where postprocessing is finished, but upload is not finished + opencloud postprocessing resume -s "finished" # Equivalent to the above + opencloud postprocessing resume -s "virusscan" # Resume all uploads currently in virusscan step + ``` + +## Metrics + +The postprocessing service exposes the following prometheus metrics at `/metrics` (as configured using the `POSTPROCESSING_DEBUG_ADDR` env var): + +| Metric Name | Type | Description | Labels | +| --- | --- | --- | --- | +| `opencloud_postprocessing_build_info` | Gauge | Build information | `version` | +| `opencloud_postprocessing_events_outstanding_acks` | Gauge | Number of outstanding acks for events | | +| `opencloud_postprocessing_events_unprocessed` | Gauge | Number of unprocessed events | | +| `opencloud_postprocessing_events_redelivered` | Gauge | Number of redelivered events | | +| `opencloud_postprocessing_in_progress` | Gauge | Number of postprocessing events in progress | | +| `opencloud_postprocessing_finished` | Counter | Number of finished postprocessing events | `status` | +| `opencloud_postprocessing_duration_seconds` | Histogram | Duration of postprocessing operations in seconds | `status` | + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy.yaml new file mode 100644 index 00000000..c76e79e0 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy.yaml @@ -0,0 +1,240 @@ +# Autogenerated +# Filename: proxy.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9205 + token: "" + pprof: false + zpages: false +http: + addr: 0.0.0.0:9200 + root: / + tls_cert: /root/.opencloud/proxy/server.crt + tls_key: /root/.opencloud/proxy/server.key + tls: true +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +grpc_client_tls: null +role_quotas: {} +policies: +- name: default + routes: + - endpoint: / + service: eu.opencloud.web.web + unprotected: true + skip_x_access_token: false + - endpoint: /.well-known/ocm + service: eu.opencloud.web.ocm + unprotected: true + skip_x_access_token: false + - endpoint: /.well-known/webfinger + service: eu.opencloud.web.webfinger + unprotected: true + skip_x_access_token: false + - endpoint: /.well-known/openid-configuration + service: eu.opencloud.web.idp + unprotected: true + skip_x_access_token: false + - endpoint: /branding/logo + service: eu.opencloud.web.web + skip_x_access_token: false + - endpoint: /konnect/ + service: eu.opencloud.web.idp + unprotected: true + skip_x_access_token: false + - endpoint: /signin/ + service: eu.opencloud.web.idp + unprotected: true + skip_x_access_token: false + - endpoint: /archiver + service: eu.opencloud.web.frontend + skip_x_access_token: false + - endpoint: /ocs/v2.php/apps/notifications/api/v1/notifications/sse + service: eu.opencloud.sse.sse + skip_x_access_token: false + - endpoint: /ocs/v2.php/apps/notifications/api/v1/notifications + service: eu.opencloud.web.userlog + skip_x_access_token: false + - type: regex + endpoint: /ocs/v[12].php/cloud/user/signing-key + service: eu.opencloud.web.ocs + skip_x_access_token: false + - type: regex + endpoint: /ocs/v[12].php/config + service: eu.opencloud.web.frontend + unprotected: true + skip_x_access_token: false + - endpoint: /sciencemesh/federations + service: eu.opencloud.web.ocm + unprotected: true + skip_x_access_token: false + - endpoint: /sciencemesh/discover + service: eu.opencloud.web.ocm + unprotected: true + skip_x_access_token: false + - endpoint: /sciencemesh/ + service: eu.opencloud.web.ocm + skip_x_access_token: false + - endpoint: /ocm/ + service: eu.opencloud.web.ocm + skip_x_access_token: false + - endpoint: /ocs/ + service: eu.opencloud.web.frontend + skip_x_access_token: false + - type: query + endpoint: /remote.php/?preview=1 + service: eu.opencloud.web.webdav + skip_x_access_token: false + - type: regex + method: REPORT + endpoint: (/remote.php)?/(web)?dav + service: eu.opencloud.web.webdav + skip_x_access_token: false + - type: query + endpoint: /dav/?preview=1 + service: eu.opencloud.web.webdav + skip_x_access_token: false + - type: query + endpoint: /webdav/?preview=1 + service: eu.opencloud.web.webdav + skip_x_access_token: false + - endpoint: /remote.php/ + service: eu.opencloud.web.frontend + skip_x_access_token: false + - endpoint: /dav/ + service: eu.opencloud.web.frontend + skip_x_access_token: false + - endpoint: /webdav/ + service: eu.opencloud.web.frontend + skip_x_access_token: false + - endpoint: /status + service: eu.opencloud.web.frontend + unprotected: true + skip_x_access_token: false + - endpoint: /status.php + service: eu.opencloud.web.frontend + unprotected: true + skip_x_access_token: false + - endpoint: /index.php/ + service: eu.opencloud.web.frontend + skip_x_access_token: false + - endpoint: /apps/ + service: eu.opencloud.web.frontend + skip_x_access_token: false + - endpoint: /data + service: eu.opencloud.web.frontend + unprotected: true + skip_x_access_token: false + - endpoint: /app/list + service: eu.opencloud.web.frontend + unprotected: true + skip_x_access_token: false + - endpoint: /app/ + service: eu.opencloud.web.frontend + skip_x_access_token: false + - endpoint: /graph/v1beta1/extensions/org.libregraph/activities + service: eu.opencloud.web.activitylog + skip_x_access_token: false + - endpoint: /graph/v1.0/invitations + service: eu.opencloud.web.invitations + skip_x_access_token: false + - endpoint: /graph/ + service: eu.opencloud.web.graph + skip_x_access_token: false + - endpoint: /api/v0/settings + service: eu.opencloud.web.settings + skip_x_access_token: false + - endpoint: /auth-app/tokens + service: eu.opencloud.web.auth-app + skip_x_access_token: false + - endpoint: /wopi + service: eu.opencloud.web.collaboration + unprotected: true + skip_x_access_token: true +additional_policies: [] +oidc: + issuer: https://localhost:9200 + insecure: false + access_token_verify_method: jwt + skip_user_info: false + user_info_cache: + store: memory + addresses: + - 127.0.0.1:9233 + database: cache-userinfo + table: "" + ttl: 10s + disable_persistence: false + username: "" + password: "" + jwks: + refresh_interval: 60 + refresh_timeout: 10 + refresh_limit: 60 + refresh_unknown_kid: true + rewrite_well_known: false +service_account: + service_account_id: "" + service_account_secret: "" +role_assignment: + driver: default + oidc_role_mapper: + role_claim: roles + role_mapping: + - role_name: admin + claim_value: opencloudAdmin + - role_name: spaceadmin + claim_value: opencloudSpaceAdmin + - role_name: user + claim_value: opencloudUser + - role_name: user-light + claim_value: opencloudGuest +policy_selector: + static: + policy: default + claims: null + regex: null +pre_signed_url: + allowed_http_methods: + - GET + enabled: true + signing_keys: + store: nats-js-kv + addresses: + - 127.0.0.1:9233 + ttl: 12h0m0s + disable_persistence: true + username: "" + password: "" +account_backend: cs3 +user_oidc_claim: preferred_username +user_cs3_claim: username +machine_auth_api_key: "" +auto_provision_accounts: false +auto_provision_claims: + username: preferred_username + email: email + display_name: name + groups: groups +enable_basic_auth: false +insecure_backends: false +backend_https_cacert: "" +auth_middleware: + credentials_by_user_agent: {} + allow_app_auth: true +policies_middleware: + query: "" +csp_config_file_location: "" +csp_config_file_override_location: "" +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_configvars.mdx new file mode 100644 index 00000000..91e5e516 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_configvars.mdx @@ -0,0 +1,68 @@ +Environment variables for the **proxy** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`PROXY_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`PROXY_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9205`| +|`PROXY_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`PROXY_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`PROXY_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`PROXY_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`0.0.0.0:9200`| +|`PROXY_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/`| +|`PROXY_TRANSPORT_TLS_CERT`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the external http services. If not defined, the root directory derives from $OC_BASE_DATA_PATH/proxy.`|`/root/.opencloud/proxy/server.crt`| +|`PROXY_TRANSPORT_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 external http services. If not defined, the root directory derives from $OC_BASE_DATA_PATH/proxy.`|`/root/.opencloud/proxy/server.key`| +|`PROXY_TLS`| 1.0.0 |bool|`Enable/Disable HTTPS for external HTTP services. Must be set to 'true' if the built-in IDP service and no reverse proxy is used. See the text description for details.`|`true`| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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_URL`
`OC_OIDC_ISSUER`
`PROXY_OIDC_ISSUER`| 1.0.0 |string|`URL of the OIDC issuer. It defaults to URL of the builtin IDP.`|`https://localhost:9200`| +|`OC_INSECURE`
`PROXY_OIDC_INSECURE`| 1.0.0 |bool|`Disable TLS certificate validation for connections to the IDP. Note that this is not recommended for production environments.`|`false`| +|`PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD`| 1.0.0 |string|`Sets how OIDC access tokens should be verified. Possible values are 'none' and 'jwt'. When using 'none', no special validation apart from using it for accessing the IDP's userinfo endpoint will be done. When using 'jwt', it tries to parse the access token as a jwt token and verifies the signature using the keys published on the IDP's 'jwks_uri'.`|`jwt`| +|`PROXY_OIDC_SKIP_USER_INFO`| 1.0.0 |bool|`Do not look up user claims at the userinfo endpoint and directly read them from the access token. Incompatible with 'PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD=none'.`|`false`| +|`OC_CACHE_STORE`
`PROXY_OIDC_USERINFO_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`
`PROXY_OIDC_USERINFO_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_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`cache-userinfo`| +|`PROXY_OIDC_USERINFO_CACHE_TABLE`| 1.0.0 |string|`The database table the store should use.`|``| +|`OC_CACHE_TTL`
`PROXY_OIDC_USERINFO_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_CACHE_DISABLE_PERSISTENCE`
`PROXY_OIDC_USERINFO_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_AUTH_USERNAME`
`PROXY_OIDC_USERINFO_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_AUTH_PASSWORD`
`PROXY_OIDC_USERINFO_CACHE_AUTH_PASSWORD`| 1.0.0 |string|`The password to authenticate with the cache. Only applies when store type 'nats-js-kv' is configured.`|``| +|`PROXY_OIDC_JWKS_REFRESH_INTERVAL`| 1.0.0 |uint64|`The interval for refreshing the JWKS (JSON Web Key Set) in minutes in the background via a new HTTP request to the IDP.`|`60`| +|`PROXY_OIDC_JWKS_REFRESH_TIMEOUT`| 1.0.0 |uint64|`The timeout in seconds for an outgoing JWKS request.`|`10`| +|`PROXY_OIDC_JWKS_REFRESH_RATE_LIMIT`| 1.0.0 |uint64|`Limits the rate in seconds at which refresh requests are performed for unknown keys. This is used to prevent malicious clients from imposing high network load on the IDP via OpenCloud.`|`60`| +|`PROXY_OIDC_JWKS_REFRESH_UNKNOWN_KID`| 1.0.0 |bool|`If set to 'true', the JWKS refresh request will occur every time an unknown KEY ID (KID) is seen. Always set a 'refresh_limit' when enabling this.`|`true`| +|`PROXY_OIDC_REWRITE_WELLKNOWN`| 1.0.0 |bool|`Enables rewriting the /.well-known/openid-configuration to the configured OIDC issuer. Needed by the Desktop Client, Android Client and iOS Client to discover the OIDC provider.`|`false`| +|`OC_SERVICE_ACCOUNT_ID`
`PROXY_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`
`PROXY_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| +|`PROXY_ROLE_ASSIGNMENT_DRIVER`| 1.0.0 |string|`The mechanism that should be used to assign roles to user upon login. Supported values: 'default' or 'oidc'. 'default' will assign the role 'user' to users which don't have a role assigned at the time they login. 'oidc' will assign the role based on the value of a claim (configured via PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM) from the users OIDC claims.`|`default`| +|`PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM`| 1.0.0 |string|`The OIDC claim used to create the users role assignment.`|`roles`| +|`PROXY_ENABLE_PRESIGNEDURLS`| 1.0.0 |bool|`Allow OCS to get a signing key to sign requests.`|`true`| +|`OC_CACHE_STORE`
`PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE`| 1.0.0 |string|`The type of the signing key store. Supported values are: 'redis-sentinel', 'nats-js-kv' and 'opencloudstoreservice' (deprecated). See the text description for details.`|`nats-js-kv`| +|`OC_CACHE_STORE_NODES`
`PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES`| 1.0.0 |[]string|`A list of nodes to access the configured store. 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_TTL`
`PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_TTL`| 1.0.0 |Duration|`Default time to live for signing keys. See the Environment Variable Types description for more details.`|`12h0m0s`| +|`OC_CACHE_DISABLE_PERSISTENCE`
`PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_DISABLE_PERSISTENCE`| 1.0.0 |bool|`Disables persistence of the store. Only applies when store type 'nats-js-kv' is configured. Defaults to true.`|`true`| +|`OC_CACHE_AUTH_USERNAME`
`PROXY_PRESIGNEDURL_SIGNING_KEYS_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_CACHE_AUTH_PASSWORD`
`PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_AUTH_PASSWORD`| 1.0.0 |string|`The password to authenticate with the store. Only applies when store type 'nats-js-kv' is configured.`|``| +|`PROXY_ACCOUNT_BACKEND_TYPE`| 1.0.0 |string|`Account backend the PROXY service should use. Currently only 'cs3' is possible here.`|`cs3`| +|`PROXY_USER_OIDC_CLAIM`| 1.0.0 |string|`The name of an OpenID Connect claim that is used for resolving users with the account backend. The value of the claim must hold a per user unique, stable and non re-assignable identifier. The availability of claims depends on your Identity Provider. There are common claims available for most Identity providers like 'email' or 'preferred_username' but you can also add your own claim.`|`preferred_username`| +|`PROXY_USER_CS3_CLAIM`| 1.0.0 |string|`The name of a CS3 user attribute (claim) that should be mapped to the 'user_oidc_claim'. Supported values are 'username', 'mail' and 'userid'.`|`username`| +|`OC_MACHINE_AUTH_API_KEY`
`PROXY_MACHINE_AUTH_API_KEY`| 1.0.0 |string|`Machine auth API key used to validate internal requests necessary to access resources from other services.`|``| +|`PROXY_AUTOPROVISION_ACCOUNTS`| 1.0.0 |bool|`Set this to 'true' to automatically provision users that do not yet exist in the users service on-demand upon first sign-in. To use this a write-enabled libregraph user backend needs to be setup an running.`|`false`| +|`PROXY_AUTOPROVISION_CLAIM_USERNAME`| 1.0.0 |string|`The name of the OIDC claim that holds the username.`|`preferred_username`| +|`PROXY_AUTOPROVISION_CLAIM_EMAIL`| 1.0.0 |string|`The name of the OIDC claim that holds the email.`|`email`| +|`PROXY_AUTOPROVISION_CLAIM_DISPLAYNAME`| 1.0.0 |string|`The name of the OIDC claim that holds the display name.`|`name`| +|`PROXY_AUTOPROVISION_CLAIM_GROUPS`| 1.0.0 |string|`The name of the OIDC claim that holds the groups.`|`groups`| +|`PROXY_ENABLE_BASIC_AUTH`| 1.0.0 |bool|`Set this to true to enable 'basic authentication' (username/password).`|`false`| +|`PROXY_INSECURE_BACKENDS`| 1.0.0 |bool|`Disable TLS certificate validation for all HTTP backend connections.`|`false`| +|`PROXY_HTTPS_CACERT`| 1.0.0 |string|`Path/File for the root CA certificate used to validate the server’s TLS certificate for https enabled backend services.`|``| +|`PROXY_ENABLE_APP_AUTH`| 1.0.0 |bool|`Allow app authentication. This can be used to authenticate 3rd party applications. Note that auth-app service must be running for this feature to work.`|`true`| +|`PROXY_POLICIES_QUERY`| 1.0.0 |string|`Defines the 'Complete Rules' variable defined in the rego rule set this step uses for its evaluation. Rules default to deny if the variable was not found.`|``| +|`PROXY_CSP_CONFIG_FILE_LOCATION`| 1.0.0 |string|`The location of the CSP configuration file.`|``| +|`PROXY_CSP_CONFIG_FILE_OVERRIDE_LOCATION`| 4.0.0 |string|`The location of the CSP configuration file override.`|``| +|`OC_EVENTS_ENDPOINT`
`PROXY_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`
`PROXY_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`
`PROXY_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`PROXY_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided PROXY_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`PROXY_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_AUTH_USERNAME`
`PROXY_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_AUTH_PASSWORD`
`PROXY_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.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_readme.mdx new file mode 100755 index 00000000..41e18440 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/proxy_readme.mdx @@ -0,0 +1,358 @@ +--- +title: Proxy +date: 2026-01-15T10:35:01.392630642Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/proxy +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The proxy service is an API-Gateway for the OpenCloud microservices. Every HTTP request goes through this service. Authentication, logging and other preprocessing of requests also happens here. Mechanisms like request rate limiting or intrusion prevention are **not** included in the proxy service and must be setup in front like with an external reverse proxy. + +The proxy service is the only service communicating to the outside and needs therefore usual protections against DDOS, Slow Loris or other attack vectors. All other services are not exposed to the outside, but also need protective measures when it comes to distributed setups like when using container orchestration over various physical servers. + + +## Table of Contents + +* [Authentication](#authentication) +* [Configuring Routes](#configuring-routes) +* [Automatic User and Group Provisioning](#automatic-user-and-group-provisioning) + * [Prequisites](#prequisites) + * [Configuration](#configuration) + * [How it Works](#how-it-works) + * [Claim Updates](#claim-updates) + * [Impacts](#impacts) +* [Automatic Quota Assignments](#automatic-quota-assignments) +* [Automatic Role Assignments](#automatic-role-assignments) +* [Recommendations for Production Deployments](#recommendations-for-production-deployments) + * [Content Security Policy](#content-security-policy) +* [Caching](#caching) +* [Presigned Urls](#presigned-urls) +* [Special Settings](#special-settings) +* [Metrics](#metrics) + * [1) Single Process Mode](#1)-single-process-mode) + * [2) Standalone Mode](#2)-standalone-mode) + * [Available Metrics](#available-metrics) + * [Prometheus Configuration](#prometheus-configuration) + +## Authentication + +The following request authentication schemes are implemented: + +- Basic Auth (Only use in development, **never in production** setups!) +- OpenID Connect +- Signed URL +- Public Share Token + +## Configuring Routes + +The proxy handles routing to all endpoints that OpenCloud offers. The currently availabe default routes can be found [in the code](https://github.com/opencloud-eu/opencloud/blob/main/services/proxy/pkg/config/defaults/defaultconfig.go). Changing or adding routes can be necessary when writing own OpenCloud extensions. + +Due to the complexity when defining routes, these can only be defined in the yaml file but not via environment variables. + +For _overwriting_ default routes, use the following yaml example: + +```yaml +policies: + - name: opencloud + routes: + - endpoint: / + service: eu.opencloud.web.web + - endpoint: /dav/ + service: eu.opencloud.web.frontend +``` + +For adding _additional_ routes to the default routes use: + +```yaml +additional_policies: + - name: opencloud + routes: + - endpoint: /custom/endpoint + service: eu.opencloud.custom.custom +``` + +A route has the following configurable parameters: + +```yaml +endpoint: "" # the url that should be routed +service: "" # the service the url should be routed to +unprotected: false # with false (default), calling the endpoint requires authorization. + # with true, anyone can call the endpoint without authorisation. +``` + +## Automatic User and Group Provisioning + +When using an external OpenID Connect IDP, the proxy can be configured to automatically provision +users upon their first login. + +### Prequisites + +A number of prerequisites must be met for automatic user provisioning to work: + +* OpenCloud must be configured to use an external OpenID Connect IDP +* The `graph` service must be configured to allow updating users and groups + (`GRAPH_LDAP_SERVER_WRITE_ENABLED`). +* One of the claim values returned by the IDP as part of the userinfo response + or the access token must be unique and stable for the user. I.e. the value + must not change for the whole lifetime of the user. This claim is configured + via the `PROXY_USER_OIDC_CLAIM` environment variable (see below). A natural + choice would e.g. be the `sub` claim which is guaranteed to be unique and + stable per IDP. If a claim like `email` or `preferred_username` is used, you + have to ensure that the user's email address or username never changes. + +### Configuration + +To enable automatic user provisioning, the following environment variables must +be set for the proxy service: + +* `PROXY_AUTOPROVISION_ACCOUNTS`\ +Set to `true` to enable automatic user provisioning. +* `PROXY_AUTOPROVISION_CLAIM_USERNAME`\ +The name of an OIDC claim whose value should be used as the username for the +autoprovsioned user in OpenCloud. Defaults to `preferred_username`. +Can also be set to e.g. `sub` to guarantee a unique and stable username. +* `PROXY_AUTOPROVISION_CLAIM_EMAIL`\ +The name of an OIDC claim whose value should be used for the `mail` attribute +of the autoprovisioned user in OpenCloud. Defaults to `email`. +* `PROXY_AUTOPROVISION_CLAIM_DISPLAYNAME`\ +The name of an OIDC claim whose value should be used for the `displayname` +attribute of the autoprovisioned user in OpenCloud. Defaults to `name`. +* `PROXY_AUTOPROVISION_CLAIM_GROUPS`\ +The name of an OIDC claim whose value should be used to maintain a user's group +membership. The claim value should contain a list of group names the user should +be a member of. Defaults to `groups`. +* `PROXY_USER_OIDC_CLAIM`\ +When resolving and authenticated OIDC user, the value of this claims is used to +lookup the user in the users service. For auto provisioning setups this usually is the +same claims as set via `PROXY_AUTOPROVISION_CLAIM_USERNAME`. +* `PROXY_USER_CS3_CLAIM`\ +This is the name of the user attribute in OpenCloud that is used to lookup the user by the +value of the `PROXY_USER_OIDC_CLAIM`. For auto provisioning setups this usually +needs to be set to `username`. + +### How it Works + +When a user logs into OpenCloud for the first time, the proxy +checks if that user already exists. This is done by querying the `users` service for users, +where the attribute set in `PROXY_USER_CS3_CLAIM` matches the value of the OIDC +claim configured in `PROXY_USER_OIDC_CLAIM`. + +If the users does not exist, the proxy will create a new user via the `graph` +service using the claim values configured in +`PROXY_AUTOPROVISION_CLAIM_USERNAME`, `PROXY_AUTOPROVISION_CLAIM_EMAIL` and +`PROXY_AUTOPROVISION_CLAIM_DISPLAYNAME`. + +If the user does already exist, the proxy checks if the displayname has changed +and updates that accordingly via `graph` service. + +Unless the claim configured via `PROXY_AUTOPROVISION_CLAIM_EMAIL` is the same +as the one set via `PROXY_USER_OIDC_CLAIM` the proxy will also check if the +email address has changed and update that as well. + +Next, the proxy will check if the user is a member of the groups configured in +`PROXY_AUTOPROVISION_CLAIM_GROUPS`. It will add the user to the groups listed +via the OIDC claim that holds the groups defined in the envvar and removes it from +all other groups that he is currently a member of. +Groups that do not exist in the external IDP yet will be created. Note: This can be a +somewhat costly operation, especially if the user is a member of a large number of +groups. If the group memberships of a user are changed in the IDP after the +first login, it can take up to 5 minutes until the changes are reflected in OpenCloud. + +### Claim Updates + +OpenID Connect (OIDC) scopes are used by an application during authentication to authorize access to a user's detail, like name, email or picture information. A scope can also contain among other things groups, roles, and permissions data. Each scope returns a set of attributes, which are called claims. The scopes an application requests, depends on which attributes the application needs. Once the user authorizes the requested scopes, the claims are returned in a token. + +These issued JWT tokens are immutable and integrity-protected. Which means, any change in the source requires issuing a new token containing updated claims. On the other hand side, there is no active synchronisation process between the identity provider (IDP) who issues the token and OpenCloud. The earliest possible time that OpenCloud will notice changes is, when the current access token has expired and a new access token is issued by the IDP, or the user logs out and relogs in. + +**NOTES** + +* For resource optimisation, OpenCloud skips any checks and updates on groupmemberships, if the last update happened less than 5min ago. + +* OpenCloud can't differentiate between a group being renamed in the IDP and users being reassigned to a different group. + +* OpenCloud does not get aware when a group is being deleted in the IDP, a new claim will not hold any information from the deleted group. OpenCloud does not track a claim history to compare. + +#### Impacts + +For shares or space memberships based on groups, a renamed or deleted group will impact accessing the resource: + +* There is no user notification about the inability accessing the resource. +* The user will only experience rejected access. +* This also applies for connected apps like the Desktop, iOS or Android app! + +To give access for rejected users on a resource, one with rights to share must update the group information. + +## Automatic Quota Assignments + +It is possible to automatically assign a specific quota to new users depending on their role. +To do this, you need to configure a mapping between roles defined by their ID and the quota in bytes. +The assignment can only be done via a `yaml` configuration and not via environment variables. +See the following `proxy.yaml` config snippet for a configuration example. + +```yaml +role_quotas: + : + : +``` + +## Automatic Role Assignments + +When users login, they do automatically get a role assigned. The automatic role assignment can be +configured in different ways. The `PROXY_ROLE_ASSIGNMENT_DRIVER` environment variable (or the `driver` +setting in the `role_assignment` section of the configuration file select which mechanism to use for +the automatic role assignment. + +When set to `default`, all users which do not have a role assigned at the time for the first login will +get the role 'user' assigned. (This is also the default behavior if `PROXY_ROLE_ASSIGNMENT_DRIVER` +is unset. + +When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` the role assignment for a user will happen +based on the values of an OpenID Connect Claim of that user. The name of the OpenID Connect Claim to +be used for the role assignment can be configured via the `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM` +environment variable. It is also possible to define a mapping of claim values to role names defined +in OpenCloud via a `yaml` configuration. See the following `proxy.yaml` snippet for an example. + +```yaml +role_assignment: + driver: oidc + oidc_role_mapper: + role_claim: opencloudRoles + role_mapping: + - role_name: admin + claim_value: myAdminRole + - role_name: spaceadmin + claim_value: mySpaceAdminRole + - role_name: user + claim_value: myUserRole + - role_name: guest + claim_value: myGuestRole +``` + +This would assign the role `admin` to users with the value `myAdminRole` in the claim `opencloudRoles`. +The role `user` to users with the values `myUserRole` in the claims `opencloudRoles` and so on. + +Claim values that are not mapped to a specific OpenCloud role will be ignored. + +Note: An OpenCloud user can only have a single role assigned. If the configured +`role_mapping` and a user's claim values result in multiple possible roles for a user, the order in +which the role mappings are defined in the configuration is important. The first role in the +`role_mappings` where the `claim_value` matches a value from the user's roles claim will be assigned +to the user. So if e.g. a user's `opencloudRoles` claim has the values `myUserRole` and +`mySpaceAdminRole` that user will get the OpenCloud role `spaceadmin` assigned (because `spaceadmin` +appears before `user` in the above sample configuration). + +If a user's claim values don't match any of the configured role mappings an error will be logged and +the user will not be able to login. + +The default `role_claim` (or `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM`) is `roles`. The default `role_mapping` is: + +```yaml +- role_name: admin + claim_value: opencloudAdmin +- role_name: spaceadmin + claim_value: opencloudSpaceAdmin +- role_name: user + claim_value: opencloudUser +- role_name: guest + claim_value: opencloudcloudGuest +``` + +## Recommendations for Production Deployments + +In a production deployment, you want to have basic authentication (`PROXY_ENABLE_BASIC_AUTH`) disabled which is the default state. You also want to setup a firewall to only allow requests to the proxy service or the reverse proxy if you have one. Requests to the other services should be blocked by the firewall. + +### Content Security Policy + +For OpenCloud, external resources like an IDP (e.g. Keycloak) or when using web office documents or web apps, require defining a CSP. If not defined, the referenced services will not work. + +To create a Content Security Policy (CSP), you need to create a yaml file containing the CSP definitions. To activate the settings, reference the file as value in the `PROXY_CSP_CONFIG_FILE_LOCATION` environment variable. For each change, a restart of the OpenCloud deployment or the proxy service is required. + +A working example for a CSP can be found in a sub path of the `config` directory of the [opencloud-compose](https://github.com/opencloud-eu/opencloud-compose/tree/main/config) deployment example. + +See the [Content Security Policy (CSP) Quick Reference Guide](https://content-security-policy.com) for a description of directives. + +## Caching + +The `proxy` service can use a configured store via `PROXY_OIDC_USERINFO_CACHE_STORE`. Possible stores are: + - `memory`: Basic in-memory store and the default. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + + +## Presigned Urls + +To authenticate presigned URLs the proxy service needs to read signing keys from a store that is populated by the ocs service. Possible stores are: + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `opencloudstoreservice`: Stores data in the legacy OpenCloud store service. Requires setting `PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES` to `eu.opencloud.api.store`. + +The `memory` store cannot be used as it does not share the memory from the ocs service signing key memory store, even in a single process. + +Make sure to configure the same store in the ocs service. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OCS_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES` to the same value as `PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES`. That way the ocs uses the same nats instance as the proxy service. + - When using the `nats-js-kv` store, it is possible to set `PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_DISABLE_PERSISTENCE` to instruct nats to not persist signing key data on disc. + - When using `opencloudstoreservice` the `PROXY_PRESIGNEDURL_SIGNING_KEYS_STORE_NODES` must be set to the service name `eu.opencloud.api.store`. It does not support TTL and stores the presigning keys indefinitely. Also, the store service needs to be started. + + +## Special Settings + +When using the OpenCloud IDP service instead of an external IDP: + +- Use the environment variable `OC_URL` to define how OpenCloud can be accessed, mandatory use `https` as protocol for the URL. +- If no reverse proxy is set up, the `PROXY_TLS` environment variable **must** be set to `true` because the embedded `libreConnect` shipped with the IDP service has a hard check if the connection is on TLS and uses the HTTPS protocol. If this mismatches, an error will be logged and no connection from the client can be established. +- `PROXY_TLS` **can** be set to `false` if a reverse proxy is used and the https connection is terminated at the reverse proxy. When setting to `false`, the communication between the reverse proxy and OpenCloud is not secured. If set to `true`, you must provide certificates. + +## Metrics + +The proxy service in OpenCloud has the ability to expose metrics in the prometheus format. The metrics are exposed on the `/metrics` endpoint. There are two ways to run the OpenCloud proxy service which has an impact on the number of metrics exposed. + +### 1) Single Process Mode +In the single process mode, all OpenCloud services are running inside a single process. This is the default mode when using the `opencloud server` command to start the services. In this mode, the proxy service exposes metrics about the proxy service itself and about the OpenCloud services it is proxying. This is due to the nature of the prometheus registry which is a singleton. The metrics exposed by the proxy service itself are prefixed with `opencloud_proxy_` and the metrics exposed by other opencloud services are prefixed with `opencloud__`. + +### 2) Standalone Mode +In this mode, the proxy service only exposes its own metrics. The metrics of the other OpenCloud services are exposed on their own metrics endpoints. + +### Available Metrics +The following metrics are exposed by the proxy service: + +| Metric Name | Description | Labels | +|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------| +| `opencloud_proxy_requests_total` | [Counter](https://prometheus.io/docs/tutorials/understanding_metric_types/#counter) metric which reports the total number of HTTP requests. | `method`: HTTP method of the request | +| `opencloud_proxy_errors_total` | [Counter](https://prometheus.io/docs/tutorials/understanding_metric_types/#counter) metric which reports the total number of HTTP requests which have failed. That counts all response codes >= 500 | `method`: HTTP method of the request | +| `opencloud_proxy_duration_seconds` | [Histogram](https://prometheus.io/docs/tutorials/understanding_metric_types/#histogram) of the time (in seconds) each request took. A histogram metric uses buckets to count the number of events that fall into each bucket. | `method`: HTTP method of the request | +| `opencloud_proxy_build_info{version}` | A metric with a constant `1` value labeled by version, exposing the version of the OpenCloud proxy service. | `version`: Build version of the proxy | + +### Prometheus Configuration +The following is an example prometheus configuration for the single process mode. It assumes that the proxy debug address is configured to bind on all interfaces `PROXY_DEBUG_ADDR=0.0.0.0:9205` and that the proxy is available via the `opencloud` service name (typically in docker-compose). The prometheus service detects the `/metrics` endpoint automatically and scrapes it every 15 seconds. + +```yaml +global: + scrape_interval: 15s +scrape_configs: + - job_name: opencloud_proxy + static_configs: + - targets: ["opencloud:9205"] +``` + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search.yaml new file mode 100644 index 00000000..aeb17def --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search.yaml @@ -0,0 +1,69 @@ +# Autogenerated +# Filename: search.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9224 + token: "" + pprof: false + zpages: false +grpc: + disabled: false + addr: 127.0.0.1:9220 + tls: null +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +grpc_client_tls: null +events: + disabled: false + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + async_uploads: true + num_consumers: 1 + debounce_duration: 1000 + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" + max_ack_pending: 1000 + ack_wait: 1m0s +engine: + type: bleve + bleve: + data_path: /root/.opencloud/search + open_search: + client: + addresses: [] + username: "" + password: "" + header: {} + ca_cert: "" + retry_on_status: [] + disable_retry: false + enable_retry_on_timeout: false + max_retries: 0 + compress_request_body: false + discover_nodes_on_start: false + discover_nodes_interval: 0s + enable_metrics: false + enable_debug_logger: false + insecure: false + resource_index: + name: opencloud-resource +extractor: + type: basic + cs3_allow_insecure: false + tika: + tika_url: http://127.0.0.1:9998 + clean_stop_words: true +content_extraction_size_limit: 20971520 +batch_size: 500 +service_account: + service_account_id: "" + service_account_secret: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_configvars.mdx new file mode 100644 index 00000000..e2f72ae1 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_configvars.mdx @@ -0,0 +1,54 @@ +Environment variables for the **search** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`SEARCH_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`SEARCH_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9224`| +|`SEARCH_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`SEARCH_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`SEARCH_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`SEARCH_GRPC_DISABLED`| 4.0.0 |bool|`Disables the GRPC service. Set this to true if the service should only handle events.`|`false`| +|`SEARCH_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9220`| +|`OC_JWT_SECRET`
`SEARCH_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`SEARCH_EVENTS_DISABLED`| 4.0.0 |bool|`Disables listening for events. Set this to true if the service should only handle GRPC requests.`|`false`| +|`OC_EVENTS_ENDPOINT`
`SEARCH_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_CLUSTER`
`SEARCH_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_ASYNC_UPLOADS`
`SEARCH_EVENTS_ASYNC_UPLOADS`| 1.0.0 |bool|`Enable asynchronous file uploads.`|`true`| +|`SEARCH_EVENTS_NUM_CONSUMERS`| 1.0.0 |int|`The amount of concurrent event consumers to start. Event consumers are used for searching files. Multiple consumers increase parallelisation, but will also increase CPU and memory demands.`|`1`| +|`SEARCH_EVENTS_REINDEX_DEBOUNCE_DURATION`| 1.0.0 |int|`The duration in milliseconds the reindex debouncer waits before triggering a reindex of a space that was modified.`|`1000`| +|`OC_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`SEARCH_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`SEARCH_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided SEARCH_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`SEARCH_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_AUTH_USERNAME`
`SEARCH_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_AUTH_PASSWORD`
`SEARCH_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.`|``| +|`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`| +|`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_ENGINE_TYPE`| 1.0.0 |string|`Defines which search engine to use. Defaults to 'bleve'. Supported values are: 'bleve'.`|`bleve`| +|`SEARCH_ENGINE_BLEVE_DATA_PATH`| 1.0.0 |string|`The directory where the filesystem will store search data. If not defined, the root directory derives from $OC_BASE_DATA_PATH/search.`|`/root/.opencloud/search`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_ADDRESSES`| 4.0.0 |[]string|`The addresses of the OpenSearch nodes..`|`[]`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_USERNAME`| 4.0.0 |string|`Username for HTTP Basic Authentication.`|``| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_PASSWORD`| 4.0.0 |string|`Password for HTTP Basic Authentication.`|``| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_HEADER`| 4.0.0 |Header|`HTTP headers to include in requests.`|`map[]`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_CA_CERT`| 4.0.0 |string|`Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the opensearch server.`|``| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_RETRY_ON_STATUS`| 4.0.0 |[]int|`HTTP status codes that trigger a retry.`|`[]`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_DISABLE_RETRY`| 4.0.0 |bool|`Disable retries on errors.`|`false`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_ENABLE_RETRY_ON_TIMEOUT`| 4.0.0 |bool|`Enable retries on timeout.`|`false`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_MAX_RETRIES`| 4.0.0 |int|`Maximum number of retries for requests.`|`0`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_COMPRESS_REQUEST_BODY`| 4.0.0 |bool|`Compress request bodies.`|`false`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_DISCOVER_NODES_ON_START`| 4.0.0 |bool|`Discover nodes on service start.`|`false`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_DISCOVER_NODES_INTERVAL`| 4.0.0 |Duration|`Interval for discovering nodes.`|`0s`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_ENABLE_METRICS`| 4.0.0 |bool|`Enable metrics collection.`|`false`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_ENABLE_DEBUG_LOGGER`| 4.0.0 |bool|`Enable debug logging.`|`false`| +|`SEARCH_ENGINE_OPEN_SEARCH_CLIENT_INSECURE`| 4.0.0 |bool|`Skip TLS certificate verification.`|`false`| +|`SEARCH_ENGINE_OPEN_SEARCH_RESOURCE_INDEX_NAME`| 4.0.0 |string|`The name of the OpenSearch index for resources.`|`opencloud-resource`| +|`SEARCH_EXTRACTOR_TYPE`| 1.0.0 |string|`Defines the content extraction engine. Defaults to 'basic'. Supported values are: 'basic' and 'tika'.`|`basic`| +|`OC_INSECURE`
`SEARCH_EXTRACTOR_CS3SOURCE_INSECURE`| 1.0.0 |bool|`Ignore untrusted SSL certificates when connecting to the CS3 source.`|`false`| +|`SEARCH_EXTRACTOR_TIKA_TIKA_URL`| 1.0.0 |string|`URL of the tika server.`|`http://127.0.0.1:9998`| +|`SEARCH_EXTRACTOR_TIKA_CLEAN_STOP_WORDS`| 1.0.0 |bool|`Defines if stop words should be cleaned or not. See the documentation for more details.`|`true`| +|`SEARCH_CONTENT_EXTRACTION_SIZE_LIMIT`| 1.0.0 |uint64|`Maximum file size in bytes that is allowed for content extraction.`|`20971520`| +|`SEARCH_BATCH_SIZE`| 1.0.0 |int|`The number of documents to process in a single batch. Defaults to 500.`|`500`| +|`OC_SERVICE_ACCOUNT_ID`
`SEARCH_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`
`SEARCH_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_readme.mdx new file mode 100755 index 00000000..8c03aa91 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/search_readme.mdx @@ -0,0 +1,159 @@ +--- +title: Search +date: 2026-01-15T10:35:01.392997921Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/search +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The search service is responsible for metadata and content extraction, +the retrieved data is indexed and made searchable. + +The search service runs out of the box with the shipped default `basic` configuration. +No further configuration is needed. + +Note that as of now, the search service cannot be scaled. +Consider using dedicated hardware for this service in case more resources are needed. + + +## Table of Contents + +* [Search backends](#search-backends) + * [Bleve](#bleve) + * [OpenSearch](#opensearch) +* [Query language](#query-language) +* [Content analysis / Extraction](#content-analysis-/-extraction) + * [Basic](#basic) + * [Tika](#tika) +* [Manually Trigger Re-Indexing a Space](#manually-trigger-re-indexing-a-space) +* [Metrics](#metrics) + +## Search backends + +To store and query the indexed data, a search backend is needed. + +As of now, the search service supports the following backends: + +- [bleve](https://github.com/blevesearch/bleve) (default) +- [opensearch](https://opensearch.org/) + +### Bleve + +Bleve is a lightweight, embedded full-text search engine written in Go and is the default search backend. +It is straightforward to set up and requires no additional services to run. + +The following optional settings can be set: + +* `SEARCH_ENGINE_BLEVE_DATA_PATH=/path/to/bleve/index` (default: `$OC_BASE_DATA_PATH/search`): Path to store the bleve index. + +### OpenSearch + +OpenSearch is a distributed, RESTful search and analytics engine capable of addressing a growing number of use cases. +Additionally, it provides advanced features like clustering, replication, and sharding. + +To enable OpenSearch as a backend, the following settings must be set: + +* `SEARCH_ENGINE_TYPE=open-search` +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_ADDRESSES=http://YOUR-OPENSEARCH.URL:9200` (comma-separated list of OpenSearch addresses) + +Additionally, the following optional settings can be set: + +* `SEARCH_ENGINE_OPEN_SEARCH_RESOURCE_INDEX_NAME=val` (default: `opencloud-resource`): Name of the OpenSearch index +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_USERNAME=val`: Username for HTTP Basic Authentication. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_PASSWORD=val`: Password for HTTP Basic Authentication. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_HEADER=val`: HTTP headers to include in requests. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_CA_CERT=val` CA certificate for TLS connections. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_RETRY_ON_STATUS=val` HTTP status codes that trigger a retry. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_DISABLE_RETRY=val` Disable retries on errors. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_ENABLE_RETRY_ON_TIMEOUT=val`: Enable retries on timeout. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_MAX_RETRIES=val`: Maximum number of retries for requests. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_COMPRESS_REQUEST_BODY=val`: Compress request bodies. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_DISCOVER_NODES_ON_START=val`: Discover nodes on service start. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_DISCOVER_NODES_INTERVAL=val`: Interval for discovering nodes. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_ENABLE_METRICS=val`: Enable metrics collection. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_ENABLE_DEBUG_LOGGER=val`: Enable debug logging. +* `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_INSECURE=val`: Skip TLS certificate verification. + +## Query language + +By default, [KQL](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference) is used as the query language. +For an overview of how to write kql queries, please read the [microsoft documentation](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference). + +Not all parts are supported, the following list gives an overview of parts that are not implemented yet: + +* Synonym operators +* Inclusion and exclusion operators +* Dynamic ranking operator +* ONEAR operator +* NEAR operator +* Date intervals + +In [this ADR](https://github.com/owncloud/ocis/blob/docs/ocis/adr/0020-file-search-query-language.md) you can read why KQL was chosen. + +## Content analysis / Extraction + +The search service supports the following content extraction methods: + +* `Basic`: enabled by default, only provides metadata extraction. +* `Tika`: needs to be installed and configured separately, provides content extraction for many file types. + +Note that the file content has to be transferred to the search service internally for content extraction, +which is resource-intensive and can lead to delays with larger documents. + +### Basic + +This extractor is the simplest one and just uses the resource information provided by OpenCloud. +It does not do any further content analysis. + +### Tika + +The main difference is that this extractor is able to analyze and extract data from more advanced file types like PDF, DOCX, PPTX, etc. +However, [Apache Tika](https://tika.apache.org/) is required for this task. +Read the [Getting Started with Apache Tika](https://tika.apache.org/2.6.0/gettingstarted.html) guide on how to install and run Tika or use a ready to run [Tika container](https://hub.docker.com/r/apache/tika). +See the [Tika container usage document](https://github.com/apache/tika-docker#usage) for a quickstart. + +As soon as Tika is installed and configured, the search service needs to be told to use it. + +The following settings must be set: + +* `SEARCH_EXTRACTOR_TYPE=tika` +* `SEARCH_EXTRACTOR_TIKA_TIKA_URL=http://YOUR-TIKA.URL` + +Additionally, the following optional settings can be set: + +* `SEARCH_EXTRACTOR_TIKA_CLEAN_STOP_WORDS=true` (default: `true`): ignore stop words like `I`, `you`, `the` during content extraction. + +## Manually Trigger Re-Indexing a Space + +The service includes a command-line interface to trigger re-indexing a space: + +```shell +opencloud search index --space $SPACE_ID +``` + +It can also be used to re-index all spaces: + +```shell +opencloud search index --all-spaces +``` + +## Metrics + +The search service exposes the following prometheus metrics at `/metrics` (as configured using the `SEARCH_DEBUG_ADDR` env var): + +| Metric Name | Type | Description | Labels | +| --- | --- | --- | --- | +| `opencloud_search_build_info` | Gauge | Build information | `version` | +| `opencloud_search_events_outstanding_acks` | Gauge | Number of outstanding acks for events | | +| `opencloud_search_events_unprocessed` | Gauge | Number of unprocessed events | | +| `opencloud_search_events_redelivered` | Gauge | Number of redelivered events | | +| `opencloud_search_search_duration_seconds` | Histogram | Duration of search operations in seconds | `status` | +| `opencloud_search_index_duration_seconds` | Histogram | Duration of indexing operations in seconds | `status` | + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings.yaml new file mode 100644 index 00000000..8eed1467 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings.yaml @@ -0,0 +1,64 @@ +# Autogenerated +# Filename: settings.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9194 + token: "" + pprof: false + zpages: false +http: + addr: 127.0.0.1:9190 + tls: + enabled: false + cert: "" + key: "" + root: / + cors: + allow_origins: + - '*' + allow_methods: + - GET + - POST + - PUT + - PATCH + - DELETE + - OPTIONS + allow_headers: + - Authorization + - Origin + - Content-Type + - Accept + - X-Requested-With + - X-Request-Id + allow_credentials: true +grpc: + addr: 127.0.0.1:9191 + tls: null +grpc_client_tls: null +metadata_config: + gateway_addr: eu.opencloud.api.storage-system + storage_addr: eu.opencloud.api.storage-system + system_user_id: "" + system_user_idp: internal + system_user_api_key: "" + cache: + store: memory + addresses: + - 127.0.0.1:9233 + database: settings-cache + files_table: settings_files + directories_table: settings_dirs + ttl: 10m0s + disable_persistence: false + username: "" + password: "" +bundles_path: "" +admin_user_id: "" +token_manager: + jwt_secret: "" +set_default_assignments: false +service_account_ids: +- service-user-id +default_language: "" +translation_path: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_configvars.mdx new file mode 100644 index 00000000..2c690dbe --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_configvars.mdx @@ -0,0 +1,40 @@ +Environment variables for the **settings** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`SETTINGS_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`SETTINGS_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9194`| +|`SETTINGS_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`SETTINGS_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`SETTINGS_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`SETTINGS_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9190`| +|`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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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.`|``| +|`SETTINGS_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/`| +|`OC_CORS_ALLOW_ORIGINS`
`SETTINGS_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_CORS_ALLOW_METHODS`
`SETTINGS_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`
`SETTINGS_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]`| +|`OC_CORS_ALLOW_CREDENTIALS`
`SETTINGS_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`| +|`SETTINGS_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9191`| +|`SETTINGS_STORAGE_GATEWAY_GRPC_ADDR`
`STORAGE_GATEWAY_GRPC_ADDR`| 1.0.0 |string|`GRPC address of the STORAGE-SYSTEM service.`|`eu.opencloud.api.storage-system`| +|`SETTINGS_STORAGE_GRPC_ADDR`
`STORAGE_GRPC_ADDR`| 1.0.0 |string|`GRPC address of the STORAGE-SYSTEM service.`|`eu.opencloud.api.storage-system`| +|`OC_SYSTEM_USER_ID`
`SETTINGS_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`
`SETTINGS_SYSTEM_USER_IDP`| 1.0.0 |string|`IDP of the OpenCloud STORAGE-SYSTEM system user.`|`internal`| +|`OC_SYSTEM_USER_API_KEY`| 1.0.0 |string|`API key for the STORAGE-SYSTEM system user.`|``| +|`OC_CACHE_STORE`
`SETTINGS_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`
`SETTINGS_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_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`settings-cache`| +|`SETTINGS_FILE_CACHE_TABLE`| 1.0.0 |string|`The database table the store should use for the file cache.`|`settings_files`| +|`SETTINGS_DIRECTORY_CACHE_TABLE`| 1.0.0 |string|`The database table the store should use for the directory cache.`|`settings_dirs`| +|`OC_CACHE_TTL`
`SETTINGS_CACHE_TTL`| 1.0.0 |Duration|`Default time to live for entries in the cache. Only applied when access tokens has no expiration. See the Environment Variable Types description for more details.`|`10m0s`| +|`OC_CACHE_DISABLE_PERSISTENCE`
`SETTINGS_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_AUTH_USERNAME`
`SETTINGS_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_AUTH_PASSWORD`
`SETTINGS_CACHE_AUTH_PASSWORD`| 1.0.0 |string|`The password to authenticate with the cache. Only applies when store type 'nats-js-kv' is configured.`|``| +|`SETTINGS_BUNDLES_PATH`| 1.0.0 |string|`The path to a JSON file with a list of bundles. If not defined, the default bundles will be loaded.`|``| +|`OC_ADMIN_USER_ID`
`SETTINGS_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_JWT_SECRET`
`SETTINGS_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`IDM_CREATE_DEMO_USERS`
`SETTINGS_SETUP_DEFAULT_ASSIGNMENTS`| 1.0.0 |bool|`The default role assignments the demo users should be setup.`|`false`| +|`SETTINGS_SERVICE_ACCOUNT_IDS`
`OC_SERVICE_ACCOUNT_ID`| 1.0.0 |[]string|`The list of all service account IDs. These will be assigned the hidden 'service-account' role. Note: When using 'OC_SERVICE_ACCOUNT_ID' this will contain only one value while 'SETTINGS_SERVICE_ACCOUNT_IDS' can have multiple. See the 'auth-service' service description for more details about service accounts.`|`[service-user-id]`| +|`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_TRANSLATION_PATH`
`SETTINGS_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.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_readme.mdx new file mode 100755 index 00000000..7a30393b --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/settings_readme.mdx @@ -0,0 +1,478 @@ +--- +title: Settings +date: 2026-01-15T10:35:01.393722349Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/settings +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `settings` service provides functionality for other services to register new settings as well as storing and retrieving the respective settings' values. + + +## Table of Contents + +* [Settings Managed](#settings-managed) +* [Caching](#caching) +* [Settings Management](#settings-management) +* [Settings Usage](#settings-usage) +* [Service Accounts](#service-accounts) +* [Translations](#translations) + * [Translation Rules](#translation-rules) +* [Default Language](#default-language) +* [Custom Roles](#custom-roles) + +## Settings Managed + +The settings service is currently used for managing the: + +* users' `profile` settings like the language and the email notification settings, +* possible user roles and their respective permissions, +* assignment of roles to users. + +As an example, user profile settings that can be changed in the Web UI must be persistent. + +The settings service persists the settings data via the `storage-system` service. + + + +## Caching + +The `settings` service caches the results of queries against the storage backend to provide faster responses. The content of this cache is independent of the cache used in the `storage-system` service as it caches directory listing and settings content stored in files. + +The store used for the cache can be configured using the `SETTINGS_CACHE_STORE` environment variable. Possible stores are: + - `memory`: Basic in-memory store and the default. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + +## Settings Management + +OpenCloud services can register *settings bundles* with the settings service. + +## Settings Usage + +Services can set or query OpenCloud *setting values* of a user from settings bundles. + +## Service Accounts + +The settings service needs to know the IDs of service accounts but it doesn't need their secrets. They can be configured using the `SETTINGS_SERVICE_ACCOUNTS_IDS` envvar. When only using one service account `OC_SERVICE_ACCOUNT_ID` can also be used. All configured service accounts will get a hidden 'service-account' role. This role contains all permissions the service account needs but will not appear calls to the list roles endpoint. It is not possible to assign the 'service-account' role to a normal user. + +## Translations + +The `settings` service has embedded translations sourced via transifex to provide a basic set of translated languages. These embedded translations are available for all deployment scenarios. In addition, the service supports custom translations, though it is currently not possible to just add custom translations to embedded ones. If custom translations are configured, the embedded ones are not used. To configure custom translations, the `SETTINGS_TRANSLATION_PATH` environment variable needs to point to a base folder that will contain the translation files. This path must be available from all instances of the userlog service, a shared storage is recommended. Translation files must be of type [.po](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html#PO-Files) or [.mo](https://www.gnu.org/software/gettext/manual/html_node/Binaries.html). For each language, the filename needs to be `settings.po` (or `settings.mo`) and stored in a folder structure defining the language code. In general the path/name pattern for a translation file needs to be: + +```text +{SETTINGS_TRANSLATION_PATH}/{language-code}/LC_MESSAGES/settings.po +``` + +The language code pattern is composed of `language[_territory]` where `language` is the base language and `_territory` is optional and defines a country. + +For example, for the language `de`, one needs to place the corresponding translation files to `{SETTINGS_TRANSLATION_PATH}/de_DE/LC_MESSAGES/settings.po`. + + + +Important: For the time being, the embedded OpenCloud Web frontend only supports the main language code but does not handle any territory. When strings are available in the language code `language_territory`, the web frontend does not see it as it only requests `language`. In consequence, any translations made must exist in the requested `language` to avoid a fallback to the default. + +### Translation Rules + +* If a requested language code is not available, the service tries to fall back to the base language if available. For example, if the requested language-code `de_DE` is not available, the service tries to fall back to translations in the `de` folder. +* If the base language `de` is also not available, the service falls back to the system's default English (`en`), +which is the source of the texts provided by the code. + +## Default Language + +The default language can be defined via the `OC_DEFAULT_LANGUAGE` environment variable. If this variable is not defined, English will be used as default. The value has the ISO 639-1 format ("de", "en", etc.) and is limited by the list supported languages. This setting can be used to set the default language for notification and invitation emails. + +Important developer note: the list of supported languages is at the moment not easy defineable, as it is the minimum intersection of languages shown in the WebUI and languages defined in the OpenCloud code for the use of notifications and userlog. Even more, not all languages where there are translations available on transifex, are available in the WebUI respectively for OpenCloud notifications, and the translation rate for existing languages is partially not that high. You will see therefore quite often English default strings though a supported language may exist and was selected. + +The `OC_DEFAULT_LANGUAGE` setting impacts the `notification` and `userlog` services and the WebUI. Note that translations must exist for all named components to be presented correctly. + +* If `OC_DEFAULT_LANGUAGE` **is not set**, the expected behavior is: + * The `notification` and `userlog` services and the WebUI use English by default until a user sets another language in the WebUI via _Account -> Language_. + * If a user sets another language in the WebUI in _Account -> Language_, then the `notification` and `userlog` services and WebUI use the language defined by the user. If no translation is found, it falls back to English. + +* If `OC_DEFAULT_LANGUAGE` **is set**, the expected behavior is: + * The `notification` and `userlog` services and the WebUI use `OC_DEFAULT_LANGUAGE` by default until a user sets another language in the WebUI via _Account -> Language_. + * If a user sets another language in the WebUI in _Account -> Language_, the `notification` and `userlog` services and WebUI use the language defined by the user. If no translation is found, it falls back to `OC_DEFAULT_LANGUAGE` and then to English. + +## Custom Roles + +It is possible to replace the default OpenCloud roles (`admin`, `user`) with custom roles that contain custom permissions. One can set `SETTINGS_BUNDLES_PATH` to the path of a `json` file containing the new roles. + +Role Example: +```json +[ + { + "id": "38071a68-456a-4553-846a-fa67bf5596cc", // ID of the role. Recommendation is to use a random uuidv4. But any unique string will do. + "name": "user-light", // Internal name of the role. This is used by the system to identify the role. Any string will do here, but it should be unique among the other roles. + "type": "TYPE_ROLE", // Always use `TYPE_ROLE` + "extension": "opencloud-roles", // Always use `opencloud-roles` + "displayName": "User Light", // DisplayName of the role used in webui + "settings": [ + ], // Permissions attached to the role. See Details below. + "resource": { + "type": "TYPE_SYSTEM" // Always use `TYPE_SYSTEM` + } + } +] +``` + +To create custom roles: +* Copy the role example to a `json` file. +* Change `id`, `name`, and `displayName` to your liking. +* Copy the desired permissions from the `user-all-permissions` example below to the `settings` array of the role. +* Set the `SETTINGS_BUNDLE_PATH` envvar to the path of the json file and start OpenCloud + +Example File: +```json +[ + { + "id": "38071a68-456a-4553-846a-fa67bf5596cc", + "name": "user-1-permission", + "type": "TYPE_ROLE", + "extension": "opencloud-roles", + "displayName": "User with one permission only", + "settings": [ + { + "id": "7d81f103-0488-4853-bce5-98dcce36d649", + "name": "Language.ReadWrite", + "displayName": "Permission to read and set the language", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_OWN" + }, + "resource": { + "type": "TYPE_SETTING", + "id": "aa8cfbe5-95d4-4f7e-a032-c3c01f5f062f" + } + } + ], + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "71881883-1768-46bd-a24d-a356a2afdf7f", + "name": "user-all-permissions", + "type": "TYPE_ROLE", + "extension": "opencloud-roles", + "displayName": "User with all available permissions", + "settings": [ + { + "id": "8e587774-d929-4215-910b-a317b1e80f73", + "name": "Accounts.ReadWrite", + "displayName": "Account Management", + "description": "This permission gives full access to everything that is related to account management.", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_USER", + "id": "all" + } + }, + { + "id": "4e41363c-a058-40a5-aec8-958897511209", + "name": "AutoAcceptShares.ReadWriteDisabled", + "displayName": "enable/disable auto accept shares", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_OWN" + }, + "resource": { + "type": "TYPE_SETTING", + "id": "ec3ed4a3-3946-4efc-8f9f-76d38b12d3a9" + } + }, + { + "id": "ed83fc10-1f54-4a9e-b5a7-fb517f5f3e01", + "name": "Logo.Write", + "displayName": "Change logo", + "description": "This permission permits to change the system logo.", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "11516bbd-7157-49e1-b6ac-d00c820f980b", + "name": "PublicLink.Write", + "displayName": "Write publiclink", + "description": "This permission allows creating public links.", + "permissionValue": { + "operation": "OPERATION_WRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SHARE" + } + }, + { + "id": "069c08b1-e31f-4799-9ed6-194b310e7244", + "name": "Shares.Write", + "displayName": "Write share", + "description": "This permission allows creating shares.", + "permissionValue": { + "operation": "OPERATION_WRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SHARE" + } + }, + { + "id": "79e13b30-3e22-11eb-bc51-0b9f0bad9a58", + "name": "Drives.Create", + "displayName": "Create Space", + "description": "This permission allows creating new spaces.", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "5de9fe0a-4bc5-4a47-b758-28f370caf169", + "name": "Drives.DeletePersonal", + "displayName": "Delete All Home Spaces", + "description": "This permission allows deleting home spaces.", + "permissionValue": { + "operation": "OPERATION_DELETE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "fb60b004-c1fa-4f09-bf87-55ce7d46ac61", + "name": "Drives.DeleteProject", + "displayName": "Delete AllSpaces", + "description": "This permission allows deleting all spaces.", + "permissionValue": { + "operation": "OPERATION_DELETE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "e9a697c5-c67b-40fc-982b-bcf628e9916d", + "name": "ReadOnlyPublicLinkPassword.Delete", + "displayName": "Delete Read-Only Public link password", + "description": "This permission permits to opt out of a public link password enforcement.", + "permissionValue": { + "operation": "OPERATION_WRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SHARE" + } + }, + { + "id": "ad5bb5e5-dc13-4cd3-9304-09a424564ea8", + "name": "EmailNotifications.ReadWriteDisabled", + "displayName": "Disable Email Notifications", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_OWN" + }, + "resource": { + "type": "TYPE_SETTING", + "id": "33ffb5d6-cd07-4dc0-afb0-84f7559ae438" + } + }, + { + "id": "522adfbe-5908-45b4-b135-41979de73245", + "name": "Groups.ReadWrite", + "displayName": "Group Management", + "description": "This permission gives full access to everything that is related to group management.", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_GROUP", + "id": "all" + } + }, + { + "id": "7d81f103-0488-4853-bce5-98dcce36d649", + "name": "Language.ReadWrite", + "displayName": "Permission to read and set the language", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SETTING", + "id": "aa8cfbe5-95d4-4f7e-a032-c3c01f5f062f" + } + }, + { + "id": "4ebaa725-bfaa-43c5-9817-78bc9994bde4", + "name": "Favorites.List", + "displayName": "List Favorites", + "description": "This permission allows listing favorites.", + "permissionValue": { + "operation": "OPERATION_READ", + "constraint": "CONSTRAINT_OWN" + }, + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "016f6ddd-9501-4a0a-8ebe-64a20ee8ec82", + "name": "Drives.List", + "displayName": "List All Spaces", + "description": "This permission allows listing all spaces.", + "permissionValue": { + "operation": "OPERATION_READ", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "b44b4054-31a2-42b8-bb71-968b15cfbd4f", + "name": "Drives.ReadWrite", + "displayName": "Manage space properties", + "description": "This permission allows managing space properties such as name and description.", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "a53e601e-571f-4f86-8fec-d4576ef49c62", + "name": "Roles.ReadWrite", + "displayName": "Role Management", + "description": "This permission gives full access to everything that is related to role management.", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_USER", + "id": "all" + } + }, + { + "id": "4e6f9709-f9e7-44f1-95d4-b762d27b7896", + "name": "Drives.ReadWritePersonalQuota", + "displayName": "Set Personal Space Quota", + "description": "This permission allows managing personal space quotas.", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "977f0ae6-0da2-4856-93f3-22e0a8482489", + "name": "Drives.ReadWriteProjectQuota", + "displayName": "Set Project Space Quota", + "description": "This permission allows managing project space quotas.", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "3d58f441-4a05-42f8-9411-ef5874528ae1", + "name": "Settings.ReadWrite", + "displayName": "Settings Management", + "description": "This permission gives full access to everything that is related to settings management.", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_USER", + "id": "all" + } + }, + { + "id": "cf3faa8c-50d9-4f84-9650-ff9faf21aa9d", + "name": "Drives.ReadWriteEnabled", + "displayName": "Space ability", + "description": "This permission allows enabling and disabling spaces.", + "permissionValue": { + "operation": "OPERATION_READWRITE", + "constraint": "CONSTRAINT_ALL" + }, + "resource": { + "type": "TYPE_SYSTEM" + } + }, + { + "id": "a54778fd-1c45-47f0-892d-655caf5236f2", + "name": "Favorites.Write", + "displayName": "Write Favorites", + "description": "This permission allows marking files as favorites.", + "permissionValue": { + "operation": "OPERATION_WRITE", + "constraint": "CONSTRAINT_OWN" + }, + "resource": { + "type": "TYPE_FILE" + } + } + ], + "resource": { + "type": "TYPE_SYSTEM" + } + } +] +``` + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing.yaml new file mode 100644 index 00000000..d88a612c --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing.yaml @@ -0,0 +1,76 @@ +# Autogenerated +# Filename: sharing.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9151 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9150 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_cert_path: "" + enable_tls: false + auth_username: "" + auth_password: "" +skip_user_groups_in_token: false +user_sharing_driver: jsoncs3 +user_sharing_drivers: + jsoncs3: + provider_addr: eu.opencloud.api.storage-system + system_user_id: "" + system_user_idp: internal + system_user_api_key: "" + cache_ttl: 0 + max_concurrency: 1 + json: + file: /root/.opencloud/storage/shares.json + cs3: + provider_addr: eu.opencloud.api.storage-system + system_user_id: "" + system_user_idp: internal + system_user_api_key: "" + owncloudsql: + db_username: owncloud + db_password: "" + db_host: mysql + db_port: 3306 + db_name: owncloud + user_storage_mount_id: "" +public_sharing_driver: jsoncs3 +public_sharing_drivers: + json: + file: /root/.opencloud/storage/publicshares.json + jsoncs3: + provider_addr: eu.opencloud.api.storage-system + system_user_id: "" + system_user_idp: internal + system_user_api_key: "" + cs3: + provider_addr: eu.opencloud.api.storage-system + system_user_id: "" + system_user_idp: internal + system_user_api_key: "" +public_sharing_writeableshare_must_have_password: false +public_sharing_share_must_have_password: true +enable_expired_shares_cleanup: true +password_policy: + min_characters: 8 + min_lowercase_characters: 1 + min_uppercase_characters: 1 + min_digits: 1 + min_special_characters: 1 + banned_passwords_list: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_configvars.mdx new file mode 100644 index 00000000..d27185d3 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_configvars.mdx @@ -0,0 +1,60 @@ +Environment variables for the **sharing** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`SHARING_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`SHARING_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9151`| +|`SHARING_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`SHARING_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`SHARING_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`SHARING_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9150`| +|`OC_GRPC_PROTOCOL`
`SHARING_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`OC_JWT_SECRET`
`SHARING_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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_EVENTS_ENDPOINT`
`SHARING_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_CLUSTER`
`SHARING_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`SHARING_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`SHARING_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_ENABLE_TLS`
`SHARING_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_AUTH_USERNAME`
`SHARING_EVENTS_AUTH_USERNAME`| 1.0.0 |string|`Username for the events broker.`|``| +|`OC_EVENTS_AUTH_PASSWORD`
`SHARING_EVENTS_AUTH_PASSWORD`| 1.0.0 |string|`Password for the events broker.`|``| +|`SHARING_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the loading of user's group memberships from the reva access token.`|`false`| +|`SHARING_USER_DRIVER`| 1.0.0 |string|`Driver to be used to persist shares. Supported values are 'jsoncs3', 'json', 'cs3' (deprecated) and 'owncloudsql'.`|`jsoncs3`| +|`SHARING_USER_JSONCS3_PROVIDER_ADDR`| 1.0.0 |string|`GRPC address of the STORAGE-SYSTEM service.`|`eu.opencloud.api.storage-system`| +|`OC_SYSTEM_USER_ID`
`SHARING_USER_JSONCS3_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`
`SHARING_USER_JSONCS3_SYSTEM_USER_IDP`| 1.0.0 |string|`IDP of the OpenCloud STORAGE-SYSTEM system user.`|`internal`| +|`OC_SYSTEM_USER_API_KEY`
`SHARING_USER_JSONCS3_SYSTEM_USER_API_KEY`| 1.0.0 |string|`API key for the STORAGE-SYSTEM system user.`|``| +|`SHARING_USER_JSONCS3_CACHE_TTL`| 1.0.0 |int|`TTL for the internal caches in seconds.`|`0`| +|`OC_MAX_CONCURRENCY`
`SHARING_USER_JSONCS3_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`| +|`SHARING_USER_JSON_FILE`| 1.0.0 |string|`Path to the JSON file where shares will be persisted. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage.`|`/root/.opencloud/storage/shares.json`| +|`SHARING_USER_CS3_PROVIDER_ADDR`| 1.0.0 |string|`GRPC address of the STORAGE-SYSTEM service.`|`eu.opencloud.api.storage-system`| +|`OC_SYSTEM_USER_ID`
`SHARING_USER_CS3_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`
`SHARING_USER_CS3_SYSTEM_USER_IDP`| 1.0.0 |string|`IDP of the OpenCloud STORAGE-SYSTEM system user.`|`internal`| +|`OC_SYSTEM_USER_API_KEY`
`SHARING_USER_CS3_SYSTEM_USER_API_KEY`| 1.0.0 |string|`API key for the STORAGE-SYSTEM system user.`|``| +|`SHARING_USER_OWNCLOUDSQL_DB_USERNAME`| 1.0.0 |string|`Username for the database.`|`owncloud`| +|`SHARING_USER_OWNCLOUDSQL_DB_PASSWORD`| 1.0.0 |string|`Password for the database.`|``| +|`SHARING_USER_OWNCLOUDSQL_DB_HOST`| 1.0.0 |string|`Hostname or IP of the database server.`|`mysql`| +|`SHARING_USER_OWNCLOUDSQL_DB_PORT`| 1.0.0 |int|`Port that the database server is listening on.`|`3306`| +|`SHARING_USER_OWNCLOUDSQL_DB_NAME`| 1.0.0 |string|`Name of the database to be used.`|`owncloud`| +|`SHARING_USER_OWNCLOUDSQL_USER_STORAGE_MOUNT_ID`| 1.0.0 |string|`Mount ID of the ownCloudSQL users storage for mapping ownCloud 10 shares.`|``| +|`SHARING_PUBLIC_DRIVER`| 1.0.0 |string|`Driver to be used to persist public shares. Supported values are 'jsoncs3', 'json' and 'cs3' (deprecated).`|`jsoncs3`| +|`SHARING_PUBLIC_JSON_FILE`| 1.0.0 |string|`Path to the JSON file where public share meta-data will be stored. This JSON file contains the information about public shares that have been created. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage.`|`/root/.opencloud/storage/publicshares.json`| +|`SHARING_PUBLIC_JSONCS3_PROVIDER_ADDR`| 1.0.0 |string|`GRPC address of the STORAGE-SYSTEM service.`|`eu.opencloud.api.storage-system`| +|`OC_SYSTEM_USER_ID`
`SHARING_PUBLIC_JSONCS3_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`
`SHARING_PUBLIC_JSONCS3_SYSTEM_USER_IDP`| 1.0.0 |string|`IDP of the OpenCloud STORAGE-SYSTEM system user.`|`internal`| +|`OC_SYSTEM_USER_API_KEY`
`SHARING_PUBLIC_JSONCS3_SYSTEM_USER_API_KEY`| 1.0.0 |string|`API key for the STORAGE-SYSTEM system user.`|``| +|`SHARING_PUBLIC_CS3_PROVIDER_ADDR`| 1.0.0 |string|`GRPC address of the STORAGE-SYSTEM service.`|`eu.opencloud.api.storage-system`| +|`OC_SYSTEM_USER_ID`
`SHARING_PUBLIC_CS3_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`
`SHARING_PUBLIC_CS3_SYSTEM_USER_IDP`| 1.0.0 |string|`IDP of the OpenCloud STORAGE-SYSTEM system user.`|`internal`| +|`OC_SYSTEM_USER_API_KEY`
`SHARING_PUBLIC_CS3_SYSTEM_USER_API_KEY`| 1.0.0 |string|`API key for the STORAGE-SYSTEM system user.`|``| +|`OC_SHARING_PUBLIC_WRITEABLE_SHARE_MUST_HAVE_PASSWORD`
`SHARING_PUBLIC_WRITEABLE_SHARE_MUST_HAVE_PASSWORD`| 1.0.0 |bool|`Set this to true if you want to enforce passwords on Uploader, Editor or Contributor shares. If not using the global OC_SHARING_PUBLIC_WRITEABLE_SHARE_MUST_HAVE_PASSWORD, you must define the FRONTEND_OCS_PUBLIC_WRITEABLE_SHARE_MUST_HAVE_PASSWORD (deprecated) in the frontend service.`|`false`| +|`OC_SHARING_PUBLIC_SHARE_MUST_HAVE_PASSWORD`
`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_PASSWORD_POLICY_DISABLED`
`SHARING_PASSWORD_POLICY_DISABLED`| 1.0.0 |bool|`Disable the password policy. Defaults to false if not set.`|`false`| +|`OC_PASSWORD_POLICY_MIN_CHARACTERS`
`SHARING_PASSWORD_POLICY_MIN_CHARACTERS`| 1.0.0 |int|`Define the minimum password length. Defaults to 8 if not set.`|`8`| +|`OC_PASSWORD_POLICY_MIN_LOWERCASE_CHARACTERS`
`SHARING_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_UPPERCASE_CHARACTERS`
`SHARING_PASSWORD_POLICY_MIN_UPPERCASE_CHARACTERS`| 1.0.0 |int|`Define the minimum number of lowercase letters. Defaults to 1 if not set.`|`1`| +|`OC_PASSWORD_POLICY_MIN_DIGITS`
`SHARING_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`
`SHARING_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`
`SHARING_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.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_readme.mdx new file mode 100755 index 00000000..c29671c8 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sharing_readme.mdx @@ -0,0 +1,65 @@ +--- +title: Sharing +date: 2026-01-15T10:35:01.394786527Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/sharing +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `sharing` service provides the CS3 Sharing API for OpenCloud. It manages user shares and public link shares, implementing the core sharing functionality. + + +## Table of Contents + +* [Overview](#overview) +* [Integration](#integration) +* [Share Types](#share-types) +* [Configuration](#configuration) +* [Scalability](#scalability) + +## Overview + +The sharing service handles: +- User-to-user shares (share a file or folder with another user) +- Public link shares (share via a public URL) +- Share permissions and roles +- Share lifecycle management (create, update, delete) + +This service works in conjunction with the storage providers (`storage-shares` and `storage-publiclink`) to persist and manage share information. + +## Integration + +The sharing service integrates with: +- `frontend` and `ocs` - Provide HTTP APIs that translate to CS3 sharing calls +- `storage-shares` - Stores and manages received shares +- `storage-publiclink` - Manages public link shares +- `graph` - Provides LibreGraph API for sharing with roles + +## Share Types + +The service supports different types of shares: +- **User shares** - Share resources with specific users +- **Group shares** - Share resources with groups +- **Public link shares** - Create public URLs for sharing +- **Federated shares** - Share with users on other OpenCloud instances (via `ocm` service) + +## Configuration + +Share behavior can be configured via environment variables: +- Password enforcement for public shares +- Auto-acceptance of shares +- Share permissions and restrictions + +See the `frontend` service README for more details on share-related configuration options. + +## Scalability + +The sharing service depends on the configured storage backends for share metadata. Scalability characteristics depend on the chosen storage backend configuration. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse.yaml new file mode 100644 index 00000000..e2767c3a --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse.yaml @@ -0,0 +1,41 @@ +# Autogenerated +# Filename: sse.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9139 + token: "" + pprof: false + zpages: false +keepalive_interval: 0s +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" +http: + addr: 127.0.0.1:9135 + root: / + cors: + allow_origins: + - '*' + allow_methods: + - GET + allow_headers: + - Authorization + - Origin + - Content-Type + - Accept + - X-Requested-With + - X-Request-Id + - Ocs-Apirequest + allow_credentials: true + tls: + enabled: false + cert: "" + key: "" +token_manager: + jwt_secret: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_configvars.mdx new file mode 100644 index 00000000..bb84edbc --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_configvars.mdx @@ -0,0 +1,27 @@ +Environment variables for the **sse** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`SSE_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`SSE_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9139`| +|`SSE_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`SSE_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`SSE_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`SSE_KEEPALIVE_INTERVAL`| 1.0.0 |Duration|`To prevent intermediate proxies from closing the SSE connection, send periodic SSE comments to keep it open.`|`0s`| +|`OC_EVENTS_ENDPOINT`
`SSE_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_CLUSTER`
`SSE_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`SSE_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`SSE_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided SSE_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`SSE_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_AUTH_USERNAME`
`SSE_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_AUTH_PASSWORD`
`SSE_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.`|``| +|`SSE_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9135`| +|`SSE_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/`| +|`OC_CORS_ALLOW_ORIGINS`
`SSE_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_CORS_ALLOW_METHODS`
`SSE_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_HEADERS`
`SSE_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_CREDENTIALS`
`SSE_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_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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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_JWT_SECRET`
`SSE_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_readme.mdx new file mode 100755 index 00000000..b0fd8e25 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/sse_readme.mdx @@ -0,0 +1,40 @@ +--- +title: SSE +date: 2026-01-15T10:35:01.394926207Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/sse +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `sse` service is responsible for sending sse (Server-Sent Events) to a user. See [What is Server-Sent Events](https://medium.com/yemeksepeti-teknoloji/what-is-server-sent-events-sse-and-how-to-implement-it-904938bffd73) for a simple introduction and examples of server sent events. + + +## Table of Contents + +* [The Log Service Ecosystem](#the-log-service-ecosystem) +* [Subscribing](#subscribing) +* [Keep SSE Connections Alive](#keep-sse-connections-alive) + +## The Log Service Ecosystem + +Log services like the `userlog`, `clientlog` and `sse` are responsible for composing notifications for a certain audience. + - The `userlog` service translates and adjusts messages to be human readable. + - The `clientlog` service composes machine readable messages, so clients can act without the need to query the server. + - The `sse` service is only responsible for sending these messages. It does not care about their form or language. + +## Subscribing + +Clients can subscribe to the `/sse` endpoint to be informed by the server when an event happens. The `sse` endpoint will respect language changes of the user without needing to reconnect. Note that SSE has a limitation of six open connections per browser which can be reached if one has opened various tabs of the Web UI pointing to the same OpenCloud instance. + +## Keep SSE Connections Alive + +Some intermediate proxies drop connections after an idle time with no activity. If this is the case, configure the `SSE_KEEPALIVE_INTERVAL` envvar. This will send periodic SSE comments to keep connections open. + + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink.yaml new file mode 100644 index 00000000..66f3b842 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink.yaml @@ -0,0 +1,23 @@ +# Autogenerated +# Filename: storage-publiclink.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9179 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9178 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +skip_user_groups_in_token: false +storage_provider: + mount_id: 7993447f-687f-490d-875c-ac95e89a62a4 diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_configvars.mdx new file mode 100644 index 00000000..151d7fe6 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_configvars.mdx @@ -0,0 +1,17 @@ +Environment variables for the **storage-publiclink** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`STORAGE_PUBLICLINK_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`STORAGE_PUBLICLINK_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9179`| +|`STORAGE_PUBLICLINK_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`STORAGE_PUBLICLINK_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`STORAGE_PUBLICLINK_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`STORAGE_PUBLICLINK_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9178`| +|`OC_GRPC_PROTOCOL`
`STORAGE_PUBLICLINK_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`OC_JWT_SECRET`
`STORAGE_PUBLICLINK_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`STORAGE_PUBLICLINK_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the loading of user's group memberships from the reva access token.`|`false`| +|`STORAGE_PUBLICLINK_STORAGE_PROVIDER_MOUNT_ID`| 1.0.0 |string|`Mount ID of this storage. Admins can set the ID for the storage in this config option manually which is then used to reference the storage. Any reasonable long string is possible, preferably this would be an UUIDv4 format.`|`7993447f-687f-490d-875c-ac95e89a62a4`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_readme.mdx new file mode 100755 index 00000000..ef660319 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-publiclink_readme.mdx @@ -0,0 +1,60 @@ +--- +title: Storage PublicLink +date: 2026-01-15T10:35:01.395029646Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/storage-publiclink +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `storage-publiclink` service provides storage backend functionality for public link shares in OpenCloud. It implements the CS3 storage provider interface specifically for working with public link shared resources. + + +## Table of Contents + +* [Overview](#overview) +* [Integration](#integration) +* [Storage Registry](#storage-registry) +* [Access Control](#access-control) +* [Scalability](#scalability) + +## Overview + +This service is part of the storage services family and is responsible for: +- Providing access to publicly shared resources +- Handling anonymous access to shared content + +## Integration + +The storage-publiclink service integrates with: +- `sharing` service - Manages and persists public link shares +- `frontend` service - Provides HTTP/WebDAV access to public links +- Storage drivers - Accesses the actual file content + +## Storage Registry + +The service is registered in the gateway's storage registry with: +- Provider ID: `7993447f-687f-490d-875c-ac95e89a62a4` +- Mount point: `/public` +- Space types: `grant` and `mountpoint` + +See the `gateway` README for more details on storage registry configuration. + +## Access Control + +Public link shares can be configured with: +- Password protection +- Expiration dates +- Read-only or read-write permissions +- Download limits + +## Scalability + +The storage-publiclink service can be scaled horizontally. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares.yaml new file mode 100644 index 00000000..4f1502c2 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares.yaml @@ -0,0 +1,24 @@ +# Autogenerated +# Filename: storage-shares.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9156 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9154 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +skip_user_groups_in_token: false +mount_id: 7639e57c-4433-4a12-8201-722fd0009154 +readonly: false +user_share_provider_endpoint: eu.opencloud.api.sharing diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_configvars.mdx new file mode 100644 index 00000000..c157ebbe --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_configvars.mdx @@ -0,0 +1,19 @@ +Environment variables for the **storage-shares** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`STORAGE_SHARES_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`STORAGE_SHARES_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9156`| +|`STORAGE_SHARES_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`STORAGE_SHARES_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`STORAGE_SHARES_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`STORAGE_SHARES_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9154`| +|`OC_GRPC_PROTOCOL`
`STORAGE_SHARES_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GRPC service.`|`tcp`| +|`OC_JWT_SECRET`
`STORAGE_SHARES_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`STORAGE_SHARES_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the loading of user's group memberships from the reva access token.`|`false`| +|`STORAGE_SHARES_MOUNT_ID`| 1.0.0 |string|`Mount ID of this storage. Admins can set the ID for the storage in this config option manually which is then used to reference the storage. Any reasonable long string is possible, preferably this would be an UUIDv4 format.`|`7639e57c-4433-4a12-8201-722fd0009154`| +|`STORAGE_SHARES_READ_ONLY`| 1.0.0 |bool|`Set this storage to be read-only.`|`false`| +|`STORAGE_SHARES_USER_SHARE_PROVIDER_ENDPOINT`| 1.0.0 |string|`GRPC endpoint of the SHARING service.`|`eu.opencloud.api.sharing`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_readme.mdx new file mode 100755 index 00000000..3b25d5fe --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-shares_readme.mdx @@ -0,0 +1,56 @@ +--- +title: Storage Shares +date: 2026-01-15T10:35:01.395127916Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/storage-shares +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `storage-shares` service provides storage backend functionality for user and group shares in OpenCloud. It implements the CS3 storage provider interface specifically for working with shared resources. + + +## Table of Contents + +* [Overview](#overview) +* [Integration](#integration) +* [Virtual Shares Folder](#virtual-shares-folder) +* [Storage Registry](#storage-registry) +* [Scalability](#scalability) + +## Overview + +This service is part of the storage services family and is responsible for: +- Providing a virtual view of received shares +- Handling access to resources shared by other users + +## Integration + +The storage-shares service integrates with: +- `sharing` service - Manages and persists shares +- `storage-users` service - Accesses the underlying file content +- `frontend` service - Provides HTTP/WebDAV access to shares + +## Virtual Shares Folder + +The service provides a virtual "Shares" folder for each user where all received shares are mounted. This allows users to access all files and folders that have been shared with them in a centralized location. + +## Storage Registry + +The service is registered in the gateway's storage registry with: +- Provider ID: `a0ca6a90-a365-4782-871e-d44447bbc668` +- Mount point: `/users/{{.CurrentUser.Id.OpaqueId}}/Shares` +- Space types: `virtual`, `grant`, and `mountpoint` + +See the `gateway` README for more details on storage registry configuration. + +## Scalability + +The storage-shares service can be scaled horizontally. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system.yaml new file mode 100644 index 00000000..872ecfae --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system.yaml @@ -0,0 +1,42 @@ +# Autogenerated +# Filename: storage-system.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9217 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9215 + tls: null + protocol: tcp +http: + addr: 127.0.0.1:9216 + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +system_user_id: "" +system_user_api_key: "" +skip_user_groups_in_token: false +cache: + store: memory + nodes: + - 127.0.0.1:9233 + database: storage-system + ttl: 24m0s + disable_persistence: false + auth_username: "" + auth_password: "" +driver: decomposed +drivers: + decomposed: + root: /root/.opencloud/storage/metadata + max_acquire_lock_cycles: 20 + lock_cycle_duration_factor: 30 +data_server_url: http://localhost:9216/data diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_configvars.mdx new file mode 100644 index 00000000..bc3ef099 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_configvars.mdx @@ -0,0 +1,32 @@ +Environment variables for the **storage-system** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`STORAGE_SYSTEM_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`STORAGE_SYSTEM_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9217`| +|`STORAGE_SYSTEM_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint`|``| +|`STORAGE_SYSTEM_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling`|`false`| +|`STORAGE_SYSTEM_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`STORAGE_SYSTEM_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9215`| +|`OC_GRPC_PROTOCOL`
`STORAGE_SYSTEM_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GPRC service.`|`tcp`| +|`STORAGE_SYSTEM_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9216`| +|`STORAGE_SYSTEM_HTTP_PROTOCOL`| 1.0.0 |string|`The transport protocol of the HTTP service.`|`tcp`| +|`OC_JWT_SECRET`
`STORAGE_SYSTEM_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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_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_API_KEY`| 1.0.0 |string|`API key for the STORAGE-SYSTEM system user.`|``| +|`STORAGE_SYSTEM_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the loading of user's group memberships from the reva access token.`|`false`| +|`OC_CACHE_STORE`
`STORAGE_SYSTEM_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`
`STORAGE_SYSTEM_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_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`storage-system`| +|`OC_CACHE_TTL`
`STORAGE_SYSTEM_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.`|`24m0s`| +|`OC_CACHE_DISABLE_PERSISTENCE`
`STORAGE_SYSTEM_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_AUTH_USERNAME`
`STORAGE_SYSTEM_CACHE_AUTH_USERNAME`| 1.0.0 |string|`Username for the configured store. Only applies when store type 'nats-js-kv' is configured.`|``| +|`OC_CACHE_AUTH_PASSWORD`
`STORAGE_SYSTEM_CACHE_AUTH_PASSWORD`| 1.0.0 |string|`Password for the configured store. Only applies when store type 'nats-js-kv' is configured.`|``| +|`STORAGE_SYSTEM_DRIVER`| 1.0.0 |string|`The driver which should be used by the service. The only supported driver is 'decomposed'. For backwards compatibility reasons it's also possible to use the 'ocis' driver and configure it using the 'decomposed' options. `|`decomposed`| +|`STORAGE_SYSTEM_OC_ROOT`| 1.0.0 |string|`Path for the directory where the STORAGE-SYSTEM service stores it's persistent data. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage.`|`/root/.opencloud/storage/metadata`| +|`STORAGE_SYSTEM_OC_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`| +|`STORAGE_SYSTEM_OC_LOCK_CYCLE_DURATION_FACTOR`| 1.0.0 |int|`When trying to lock files, OpenCloud will multiply the cycle with this factor and use it as a millisecond timeout. Values of 0 or below will be ignored and the default value of 30 will be used.`|`30`| +|`STORAGE_SYSTEM_DATA_SERVER_URL`| 1.0.0 |string|`URL of the data server, needs to be reachable by other services using this service.`|`http://localhost:9216/data`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_readme.mdx new file mode 100755 index 00000000..245ccf1c --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-system_readme.mdx @@ -0,0 +1,41 @@ +--- +title: Storage-System +date: 2026-01-15T10:35:01.395228556Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/storage-system +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The OpenCloud Storage-System service persists and caches user related data that is defined via OpenCloud. This can be among other data role assignments, user settings and users shares. + + +## Table of Contents + +* [Caching](#caching) + +## Caching + +The `storage-system` service caches file metadata via the configured store in `STORAGE_SYSTEM_CACHE_STORE`. Possible stores are: + - `memory`: Basic in-memory store and the default. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users.yaml new file mode 100644 index 00000000..00ca85b3 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users.yaml @@ -0,0 +1,195 @@ +# Autogenerated +# Filename: storage-users.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9159 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9157 + tls: null + protocol: tcp +http: + addr: 127.0.0.1:9158 + protocol: tcp + prefix: data + cors: + allow_origins: + - https://localhost:9200 + allow_methods: + - POST + - HEAD + - PATCH + - OPTIONS + - GET + - DELETE + allow_headers: + - Authorization + - Origin + - X-Requested-With + - X-Request-Id + - X-HTTP-Method-Override + - Content-Type + - Upload-Length + - Upload-Offset + - Tus-Resumable + - Upload-Metadata + - Upload-Defer-Length + - Upload-Concat + - Upload-Incomplete + - Upload-Draft-Interop-Version + allow_credentials: false + expose_headers: + - Upload-Offset + - Location + - Upload-Length + - Tus-Version + - Tus-Resumable + - Tus-Max-Size + - Tus-Extension + - Upload-Metadata + - Upload-Defer-Length + - Upload-Concat + - Upload-Incomplete + - Upload-Draft-Interop-Version + max_age: 86400 +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +skip_user_groups_in_token: false +graceful_shutdown_timeout: 30 +driver: posix +drivers: + decomposed: + propagator: sync + async_propagator_options: + propagation_delay: 0s + root: /root/.opencloud/storage/users + user_layout: '{{.Id.OpaqueId}}' + permissions_endpoint: eu.opencloud.api.settings + personalspacealias_template: '{{.SpaceType}}/{{.User.Username | lower}}' + personalspacepath_template: "" + generalspacealias_template: '{{.SpaceType}}/{{.SpaceName | replace " " "-" | lower}}' + generalspacepath_template: "" + share_folder: /Shares + max_acquire_lock_cycles: 20 + lock_cycle_duration_factor: 30 + max_concurrency: 5 + async_uploads: true + max_quota: 0 + disable_versioning: false + decomposeds3: + propagator: sync + async_propagator_options: + propagation_delay: 0s + root: /root/.opencloud/storage/users + user_layout: '{{.Id.OpaqueId}}' + permissions_endpoint: eu.opencloud.api.settings + region: default + access_key: "" + secret_key: "" + endpoint: "" + bucket: "" + put_object_disable_content_sha254: false + put_object_disable_multipart: false + put_object_send_content_md5: true + put_object_concurrent_stream_parts: false + put_object_num_threads: 4 + put_object_part_size: 0 + personalspacealias_template: '{{.SpaceType}}/{{.User.Username | lower}}' + personalspacepath_template: "" + generalspacealias_template: '{{.SpaceType}}/{{.SpaceName | replace " " "-" | lower}}' + generalspacepath_template: "" + share_folder: /Shares + max_acquire_lock_cycles: 20 + lock_cycle_duration_factor: 30 + max_concurrency: 5 + async_uploads: true + disable_versioning: false + owncloudsql: + root: /root/.opencloud/storage/owncloud + share_folder: /Shares + user_layout: '{{.Username}}' + upload_info_dir: /root/.opencloud/storage/uploadinfo + db_username: owncloud + db_password: owncloud + db_host: "" + db_port: 3306 + db_name: owncloud + users_provider_endpoint: eu.opencloud.api.users + posix: + root: /root/.opencloud/storage/users + propagator: "" + async_propagator_options: + propagation_delay: 0s + personalspacealias_template: '{{.SpaceType}}/{{.User.Username | lower}}' + personalspacepath_template: users/{{.User.Id.OpaqueId}} + generalspacealias_template: '{{.SpaceType}}/{{.SpaceName | replace " " "-" | lower}}' + generalspacepath_template: projects/{{.SpaceId}} + permissions_endpoint: eu.opencloud.api.settings + async_uploads: true + scan_debounce_delay: 1s + max_quota: 0 + max_acquire_lock_cycles: 0 + lock_cycle_duration_factor: 0 + max_concurrency: 0 + disable_versioning: false + use_space_groups: false + enable_fs_revisions: false + watch_fs: false + watch_type: "" + watch_path: "" + watch_notification_brokers: "" + watch_root: "" + inotify_stats_frequency: 5m0s +data_server_url: http://localhost:9158/data +data_gateway_url: http://localhost:9140/data +transfer_expires: 86400 +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_cert_path: "" + enable_tls: false + num_consumers: 0 + username: "" + password: "" +filemetadata_cache: + store: memory + nodes: + - 127.0.0.1:9233 + database: storage-users + ttl: 24m0s + disable_persistence: false + username: "" + password: "" +id_cache: + store: nats-js-kv + nodes: + - 127.0.0.1:9233 + database: ids-storage-users + ttl: 24m0s + disable_persistence: false + username: "" + password: "" +mount_id: "" +expose_data_server: false +readonly: false +upload_expiration: 86400 +tasks: + purge_trash_bin: + user_id: "" + personal_delete_before: 720h0m0s + project_delete_before: 720h0m0s +service_account: + service_account_id: "" + service_account_secret: "" +gateway_addr: 127.0.0.1:9142 +machine_auth_api_key: "" +max_attempts_rename_file: 0 diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_configvars.mdx new file mode 100644 index 00000000..4619d06d --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_configvars.mdx @@ -0,0 +1,147 @@ + +2026-01-15-10-34-53 + +# Deprecation Notice + +| Deprecation Info | Deprecation Version | Removal Version | Deprecation Replacement | +|---|---|---|:---| +| | 4.0.0 | | | +Environment variables for the **storage-users** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`STORAGE_USERS_SERVICE_NAME`| 1.0.0 |string|`Service name to use. Change this when starting an additional storage provider with a custom configuration to prevent it from colliding with the default 'storage-users' service.`|`storage-users`| +|`OC_LOG_LEVEL`
`STORAGE_USERS_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`STORAGE_USERS_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9159`| +|`STORAGE_USERS_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`STORAGE_USERS_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`STORAGE_USERS_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`STORAGE_USERS_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9157`| +|`OC_GRPC_PROTOCOL`
`STORAGE_USERS_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GPRC service.`|`tcp`| +|`STORAGE_USERS_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9158`| +|`STORAGE_USERS_HTTP_PROTOCOL`| 1.0.0 |string|`The transport protocol of the HTTP service.`|`tcp`| +|`OC_CORS_ALLOW_ORIGINS`
`STORAGE_USERS_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.`|`[https://localhost:9200]`| +|`OC_CORS_ALLOW_METHODS`
`STORAGE_USERS_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.`|`[POST HEAD PATCH OPTIONS GET DELETE]`| +|`OC_CORS_ALLOW_HEADERS`
`STORAGE_USERS_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 X-Requested-With X-Request-Id X-HTTP-Method-Override Content-Type Upload-Length Upload-Offset Tus-Resumable Upload-Metadata Upload-Defer-Length Upload-Concat Upload-Incomplete Upload-Draft-Interop-Version]`| +|`OC_CORS_ALLOW_CREDENTIALS`
`STORAGE_USERS_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.`|`false`| +|`OC_CORS_EXPOSE_HEADERS`
`STORAGE_USERS_CORS_EXPOSE_HEADERS`| 1.0.0 |[]string|`A list of exposed CORS headers. See following chapter for more details: *Access-Control-Expose-Headers* at \https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers. See the Environment Variable Types description for more details.`|`[Upload-Offset Location Upload-Length Tus-Version Tus-Resumable Tus-Max-Size Tus-Extension Upload-Metadata Upload-Defer-Length Upload-Concat Upload-Incomplete Upload-Draft-Interop-Version]`| +|`OC_CORS_MAX_AGE`
`STORAGE_USERS_CORS_MAX_AGE`| 1.0.0 |uint|`The max cache duration of preflight headers. See following chapter for more details: *Access-Control-Max-Age* at \https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age. See the Environment Variable Types description for more details.`|`86400`| +|`OC_JWT_SECRET`
`STORAGE_USERS_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`STORAGE_USERS_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the loading of user's group memberships from the reva access token.`|`false`| +|`STORAGE_USERS_GRACEFUL_SHUTDOWN_TIMEOUT`| 1.0.0 |int|`The number of seconds to wait for the 'storage-users' service to shutdown cleanly before exiting with an error that gets logged. Note: This setting is only applicable when running the 'storage-users' service as a standalone service. See the text description for more details.`|`30`| +|`STORAGE_USERS_DRIVER`| 1.0.0 |string|`The storage driver which should be used by the service. Defaults to 'posix'. Supported values are: 'posix', 'decomposed', 'decomposeds3' and 'owncloudsql'. For backwards compatibility reasons it's also possible to use the 'ocis' and 's3ng' driver and configure them using the 'decomposed'/'decomposeds3' options. The 'posix' driver stores data directly on a POSIX-compliant filesystem. The 'decomposed' driver stores all data (blob and meta data) in a POSIX compliant volume. The 'decomposeds3' driver stores metadata in a POSIX compliant volume and uploads blobs to the s3 bucket.`|`posix`| +|`OC_DECOMPOSEDFS_PROPAGATOR`
`STORAGE_USERS_DECOMPOSED_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`| +|`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_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.`|`/root/.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_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_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`| +|`STORAGE_USERS_DECOMPOSED_LOCK_CYCLE_DURATION_FACTOR`| 1.0.0 |int|`When trying to lock files, OpenCloud will multiply the cycle with this factor and use it as a millisecond timeout. Values of 0 or below will be ignored and the default value will be used.`|`30`| +|`OC_MAX_CONCURRENCY`
`STORAGE_USERS_DECOMPOSED_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.`|`5`| +|`OC_ASYNC_UPLOADS`| 1.0.0 |bool|`Enable asynchronous file uploads.`|`true`| +|`OC_SPACES_MAX_QUOTA`
`STORAGE_USERS_DECOMPOSED_MAX_QUOTA`| 1.0.0 |uint64|`Set a global max quota for spaces in bytes. A value of 0 equals unlimited. If not using the global OC_SPACES_MAX_QUOTA, you must define the FRONTEND_MAX_QUOTA in the frontend service.`|`0`| +|`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_DECOMPOSEDFS_PROPAGATOR`
`STORAGE_USERS_DECOMPOSEDS3_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`| +|`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_DECOMPOSEDS3_ROOT`| 1.0.0 |string|`The directory where the filesystem storage will store metadata for blobs. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage/users.`|`/root/.opencloud/storage/users`| +|`STORAGE_USERS_DECOMPOSEDS3_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_DECOMPOSEDS3_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_DECOMPOSEDS3_REGION`| 1.0.0 |string|`Region of the S3 bucket.`|`default`| +|`STORAGE_USERS_DECOMPOSEDS3_ACCESS_KEY`| 1.0.0 |string|`Access key for the S3 bucket.`|``| +|`STORAGE_USERS_DECOMPOSEDS3_SECRET_KEY`| 1.0.0 |string|`Secret key for the S3 bucket.`|``| +|`STORAGE_USERS_DECOMPOSEDS3_ENDPOINT`| 1.0.0 |string|`Endpoint for the S3 bucket.`|``| +|`STORAGE_USERS_DECOMPOSEDS3_BUCKET`| 1.0.0 |string|`Name of the S3 bucket.`|``| +|`STORAGE_USERS_DECOMPOSEDS3_PUT_OBJECT_DISABLE_CONTENT_SHA256`| 1.0.0 |bool|`Disable sending content sha256 when copying objects to S3.`|`false`| +|`STORAGE_USERS_DECOMPOSEDS3_PUT_OBJECT_DISABLE_MULTIPART`| 1.0.0 |bool|`Disable multipart uploads when copying objects to S3.`|`false`| +|`STORAGE_USERS_DECOMPOSEDS3_PUT_OBJECT_SEND_CONTENT_MD5`| 1.0.0 |bool|`Send a Content-MD5 header when copying objects to S3.`|`true`| +|`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_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_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`| +|`STORAGE_USERS_DECOMPOSEDS3_LOCK_CYCLE_DURATION_FACTOR`| 1.0.0 |int|`When trying to lock files, OpenCloud will multiply the cycle with this factor and use it as a millisecond timeout. Values of 0 or below will be ignored and the default value of 30 will be used.`|`30`| +|`OC_MAX_CONCURRENCY`
`STORAGE_USERS_DECOMPOSEDS3_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 of 100 will be used.`|`5`| +|`OC_ASYNC_UPLOADS`| 1.0.0 |bool|`Enable asynchronous file uploads.`|`true`| +|`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`| +|`STORAGE_USERS_OWNCLOUDSQL_DATADIR`| 1.0.0 |string|`The directory where the filesystem storage will store SQL migration data. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage/owncloud.`|`/root/.opencloud/storage/owncloud`| +|`STORAGE_USERS_OWNCLOUDSQL_SHARE_FOLDER`| 1.0.0 |string|`Name of the folder jailing all shares.`|`/Shares`| +|`STORAGE_USERS_OWNCLOUDSQL_LAYOUT`| 1.0.0 |string|`Path layout to use to navigate into a users folder in an owncloud data directory`|`{{.Username}}`| +|`STORAGE_USERS_OWNCLOUDSQL_UPLOADINFO_DIR`| 1.0.0 |string|`The directory where the filesystem will store uploads temporarily. If not defined, the root directory derives from $OC_BASE_DATA_PATH/storage/uploadinfo.`|`/root/.opencloud/storage/uploadinfo`| +|`STORAGE_USERS_OWNCLOUDSQL_DB_USERNAME`| 1.0.0 |string|`Username for the database.`|`owncloud`| +|`STORAGE_USERS_OWNCLOUDSQL_DB_PASSWORD`| 1.0.0 |string|`Password for the database.`|`owncloud`| +|`STORAGE_USERS_OWNCLOUDSQL_DB_HOST`| 1.0.0 |string|`Hostname or IP of the database server.`|``| +|`STORAGE_USERS_OWNCLOUDSQL_DB_PORT`| 1.0.0 |int|`Port that the database server is listening on.`|`3306`| +|`STORAGE_USERS_OWNCLOUDSQL_DB_NAME`| 1.0.0 |string|`Name of the database to be used.`|`owncloud`| +|`STORAGE_USERS_OWNCLOUDSQL_USERS_PROVIDER_ENDPOINT`| 1.0.0 |string|`Endpoint of the users provider.`|`eu.opencloud.api.users`| +|`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.`|`/root/.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_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_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`| +|`STORAGE_USERS_POSIX_SCAN_DEBOUNCE_DELAY`| 1.0.0 |Duration|`The time in milliseconds to wait before scanning the filesystem for changes after a change has been detected.`|`1s`| +|`OC_SPACES_MAX_QUOTA`
`STORAGE_USERS_POSIX_MAX_QUOTA`| 2.0.0 |uint64|`Set a global max quota for spaces in bytes. A value of 0 equals unlimited. If not using the global OC_SPACES_MAX_QUOTA, you must define the FRONTEND_MAX_QUOTA in the frontend service.`|`0`| +|`STORAGE_USERS_POSIX_MAX_ACQUIRE_LOCK_CYCLES`| 2.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.`|`0`| +|`STORAGE_USERS_POSIX_LOCK_CYCLE_DURATION_FACTOR`| 2.0.0 |int|`When trying to lock files, OpenCloud will multiply the cycle with this factor and use it as a millisecond timeout. Values of 0 or below will be ignored and the default value will be used.`|`0`| +|`OC_MAX_CONCURRENCY`
`STORAGE_USERS_POSIX_MAX_CONCURRENCY`| 2.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_DISABLE_VERSIONING`| 2.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`| +|`STORAGE_USERS_POSIX_USE_SPACE_GROUPS`| 1.0.0 |bool|`Use space groups to manage permissions on spaces.`|`false`| +|`STORAGE_USERS_POSIX_ENABLE_FS_REVISIONS`| 1.0.0 |bool|`Allow for generating revisions from changes done to the local storage. Note: This doubles the number of bytes stored on disk because a copy of the current revision is stored to be turned into a revision later.`|`false`| +|`STORAGE_USERS_POSIX_WATCH_FS`| 2.0.0 |bool|`Enable the filesystem watcher to detect changes to the filesystem. This is used to detect changes to the filesystem and update the metadata accordingly.`|`false`| +|`STORAGE_USERS_POSIX_WATCH_TYPE`| 1.0.0 |string|`Type of the watcher to use for getting notified about changes to the filesystem. Currently available options are 'inotifywait' (default), 'cephfs', 'gpfswatchfolder' and 'gpfsfileauditlogging'.`|``| +|`STORAGE_USERS_POSIX_WATCH_PATH`| 1.0.0 |string|`Path to the watch directory/file. Only applies to the 'gpfsfileauditlogging' and 'inotifywait' watcher, in which case it is the path of the file audit log file/base directory to watch.`|``| +|`STORAGE_USERS_POSIX_WATCH_NOTIFICATION_BROKERS,STORAGE_USERS_POSIX_WATCH_FOLDER_KAFKA_BROKERS`| 1.0.0 |string|`Comma-separated list of kafka brokers to read the watchfolder events from.`|``| +|`STORAGE_USERS_POSIX_WATCH_ROOT`| 4.0.0 |string|`Path to the watch root directory. Event paths will be considered relative to this path. Only applies to the 'gpswatchfolder' and 'cephfs' watchers.`|``| +|`STORAGE_USERS_POSIX_INOTIFY_STATS_FREQUENCY`| 4.0.0 |Duration|`Frequency to log inotify stats.`|`5m0s`| +|`STORAGE_USERS_DATA_SERVER_URL`| 1.0.0 |string|`URL of the data server, needs to be reachable by the data gateway provided by the frontend service or the user if directly exposed.`|`http://localhost:9158/data`| +|`STORAGE_USERS_DATA_GATEWAY_URL`| 1.0.0 |string|`URL of the data gateway server`|`http://localhost:9140/data`| +|`STORAGE_USERS_TRANSFER_EXPIRES`| 1.0.0 |int64|`The time after which the token for upload postprocessing expires`|`86400`| +|`OC_EVENTS_ENDPOINT`
`STORAGE_USERS_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_CLUSTER`
`STORAGE_USERS_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`STORAGE_USERS_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`STORAGE_USERS_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided STORAGE_USERS_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`STORAGE_USERS_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`| +|`STORAGE_USERS_EVENTS_NUM_CONSUMERS`| 1.0.0 |int|`The amount of concurrent event consumers to start. Event consumers are used for post-processing files. Multiple consumers increase parallelisation, but will also increase CPU and memory demands. The setting has no effect when the OC_ASYNC_UPLOADS is set to false. The default and minimum value is 1.`|`0`| +|`OC_EVENTS_AUTH_USERNAME`
`STORAGE_USERS_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_AUTH_PASSWORD`
`STORAGE_USERS_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_CACHE_STORE`
`STORAGE_USERS_FILEMETADATA_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`
`STORAGE_USERS_FILEMETADATA_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_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`storage-users`| +|`OC_CACHE_TTL`
`STORAGE_USERS_FILEMETADATA_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.`|`24m0s`| +|`OC_CACHE_DISABLE_PERSISTENCE`
`STORAGE_USERS_FILEMETADATA_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_AUTH_USERNAME`
`STORAGE_USERS_FILEMETADATA_CACHE_AUTH_USERNAME`| 1.0.0 |string|`The username to authenticate with the cache store. Only applies when store type 'nats-js-kv' is configured.`|``| +|`OC_CACHE_AUTH_PASSWORD`
`STORAGE_USERS_FILEMETADATA_CACHE_AUTH_PASSWORD`| 1.0.0 |string|`The password to authenticate with the cache store. Only applies when store type 'nats-js-kv' is configured.`|``| +|`OC_CACHE_STORE`
`STORAGE_USERS_ID_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.`|`nats-js-kv`| +|`OC_CACHE_STORE_NODES`
`STORAGE_USERS_ID_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_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`ids-storage-users`| +|`OC_CACHE_TTL`
`STORAGE_USERS_ID_CACHE_TTL`| 1.0.0 |Duration|`Default time to live for user info in the user info cache. Only applied when access tokens have no expiration. Defaults to 300s which is derived from the underlaying package though not explicitly set as default. See the Environment Variable Types description for more details.`|`24m0s`| +|`OC_CACHE_DISABLE_PERSISTENCE`
`STORAGE_USERS_ID_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_AUTH_USERNAME`
`STORAGE_USERS_ID_CACHE_AUTH_USERNAME`| 1.0.0 |string|`The username to authenticate with the cache store. Only applies when store type 'nats-js-kv' is configured.`|``| +|`OC_CACHE_AUTH_PASSWORD`
`STORAGE_USERS_ID_CACHE_AUTH_PASSWORD`| 1.0.0 |string|`The password to authenticate with the cache store. Only applies when store type 'nats-js-kv' is configured.`|``| +|`STORAGE_USERS_MOUNT_ID`| 1.0.0 |string|`Mount ID of this storage.`|``| +|`STORAGE_USERS_EXPOSE_DATA_SERVER`| 1.0.0 |bool|`Exposes the data server directly to users and bypasses the data gateway. Ensure that the data server address is reachable by users.`|`false`| +|`STORAGE_USERS_READ_ONLY`| 1.0.0 |bool|`Set this storage to be read-only.`|`false`| +|`STORAGE_USERS_UPLOAD_EXPIRATION`| 1.0.0 |int64|`Duration in seconds after which uploads will expire. Note that when setting this to a low number, uploads could be cancelled before they are finished and return a 403 to the user.`|`86400`| +|`OC_ADMIN_USER_ID`
`STORAGE_USERS_PURGE_TRASH_BIN_USER_ID`| 1.0.0 |string|`ID of the user who collects all necessary information for deletion. Consider that the UUID can be encoded in some LDAP deployment configurations like in .ldif files. These need to be decoded beforehand.`|``| +|`STORAGE_USERS_PURGE_TRASH_BIN_PERSONAL_DELETE_BEFORE`| 1.0.0 |Duration|`Specifies the period of time in which items that have been in the personal trash-bin for longer than this value should be deleted. A value of 0 means no automatic deletion. See the Environment Variable Types description for more details.`|`720h0m0s`| +|`STORAGE_USERS_PURGE_TRASH_BIN_PROJECT_DELETE_BEFORE`| 1.0.0 |Duration|`Specifies the period of time in which items that have been in the project trash-bin for longer than this value should be deleted. A value of 0 means no automatic deletion. See the Environment Variable Types description for more details.`|`720h0m0s`| +|`OC_SERVICE_ACCOUNT_ID`
`STORAGE_USERS_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`
`STORAGE_USERS_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| +|`OC_GATEWAY_GRPC_ADDR`
`STORAGE_USERS_GATEWAY_GRPC_ADDR`| 1.0.0 |string|`The bind address of the gateway GRPC address.`|`127.0.0.1:9142`| +|`OC_MACHINE_AUTH_API_KEY`
`STORAGE_USERS_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.`|``| +|`STORAGE_USERS_CLI_MAX_ATTEMPTS_RENAME_FILE`| 1.0.0 |int|`The maximum number of attempts to rename a file when a user restores a file to an existing destination with the same name. The minimum value is 100.`|`0`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_deprecation.mdx new file mode 100644 index 00000000..c59cea0d --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_deprecation.mdx @@ -0,0 +1,4 @@ + +:::danger +storage-users has deprecated environment variables. Please refer to the table below for more information. +::: \ No newline at end of file diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_readme.mdx new file mode 100755 index 00000000..81c7e472 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/storage-users_readme.mdx @@ -0,0 +1,256 @@ +--- +title: Storage-Users +date: 2026-01-15T10:35:01.395362236Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/storage-users +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +Purpose and description to be added + + +## Table of Contents + +* [Graceful Shutdown](#graceful-shutdown) +* [CLI Commands](#cli-commands) + * [Manage Unfinished Uploads](#manage-unfinished-uploads) + * [Sessions command](#sessions-command) + * [Command Examples](#command-examples) + * [Manage Trash-Bin Items](#manage-trash-bin-items) + * [Purge Expired](#purge-expired) + * [List and Restore Trash-Bins Items](#list-and-restore-trash-bins-items) +* [Caching](#caching) + +## Graceful Shutdown + +You can define a graceful shutdown period for the `storage-users` service. + +IMPORTANT: The graceful shutdown period is only applicable if the `storage-users` service runs as standalone service. It does not apply if the `storage-users` service runs as part of the single binary or as single Docker environment. To build an environment where the `storage-users` service runs as a standalone service, you must start two instances, one _without_ the `storage-users` service and one _only with_ the the `storage-users` service. Note that both instances must be able to communicate on the same network. + +When hard-stopping OpenCloud, for example with the `kill ` command (SIGKILL), it is possible and likely that not all data from the decomposedfs (metadata) has been written to the storage which may result in an inconsistent decomposedfs. When gracefully shutting down OpenCloud, using a command like SIGTERM, the process will no longer accept any write requests from _other_ services and will try to write the internal open requests which can take an undefined duration based on many factors. To mitigate that situation, the following things have been implemented: + +* With the value of the environment variable `STORAGE_USERS_GRACEFUL_SHUTDOWN_TIMEOUT`, the `storage-users` service will delay its shutdown giving it time to finalize writing necessary data. This delay can be necessary if there is a lot of data to be saved and/or if storage access/thruput is slow. In such a case you would receive an error log entry informing you that not all data could be saved in time. To prevent such occurrences, you must increase the default value. + +* If a shutdown error has been logged, the command-line maintenance tool to inspect and manipulate node metadata can help to fix the issue. Please contact support for details. + +## CLI Commands + +For any command listed, use `--help` to get more details and possible options and arguments. + +To authenticate CLI commands use: + +* `OC_SERVICE_ACCOUNT_SECRET=` and +* `OC_SERVICE_ACCOUNT_ID=`. + +The `storage-users` CLI tool uses the default address to establish the connection to the `gateway` service. If the connection fails, check your custom `gateway` service `GATEWAY_GRPC_ADDR` configuration and set the same address in `storage-users` `OC_GATEWAY_GRPC_ADDR` or `STORAGE_USERS_GATEWAY_GRPC_ADDR`. + +### Manage Unfinished Uploads + + + +When using OpenCloud as user storage, a directory named `storage/users/uploads` can be found in the OpenCloud data folder. This is an intermediate directory based on [TUS](https://tus.io) which is an open protocol for resumable uploads. Each upload consists of a _blob_ and a _blob.info_ file. Note that the term _blob_ is just a placeholder. + +* **If an upload succeeds**, the _blob_ file will be moved to the target and the _blob.info_ file will be deleted. + +* **In case of incomplete uploads**, the _blob_ and _blob.info_ files will continue to receive data until either the upload succeeds in time or the upload expires based on the `STORAGE_USERS_UPLOAD_EXPIRATION` variable, see the table below for details. + +* **In case of expired uploads**, the _blob_ and _blob.info_ files will _not_ be removed automatically. Thus a lot of data can pile up over time wasting storage space. + +* **In the rare case of a failure**, after the upload succeeded but the file was not moved to its target location, which can happen when postprocessing fails, the situation is the same as with expired uploads. + +Example cases for expired uploads: + +* When a user uploads a big file but the file exceeds the user-quota, the upload can't be moved to the target after it has finished. The file stays at the upload location until it is manually cleared. + +* If the bandwidth is limited and the file to transfer can't be transferred completely before the upload expiration time is reached, the file expires and can't be processed. + +* If the upload was technically successful, but the postprocessing step failed due to an internal error, it will not get further processed. See the procedure **Resume Post-Processing** in the `postprocessing` service documentation for details how to solve this. + +The following commands are available to manage unfinished uploads: + +```bash +opencloud storage-users uploads +``` + +```plaintext +COMMANDS: + sessions Print a list of upload sessions +``` + +#### Sessions command + +The `sessions` command is the entry point for listing, restarting and cleaning unfinished uploads. + +**IMPORTANT** +> If not noted otherwise, commands with the `restart` option can also use the `resume` option. This changes behaviour slightly. +> +> * `restart`\ +> When restarting an upload, all steps for open items will be restarted, except if otherwise defined. +> * `resume`\ +> When resuming an upload, processing will continue unfinished items from their last completed step. + +```bash +opencloud storage-users uploads sessions +``` + +``` +NAME: + opencloud storage-users uploads sessions - Print a list of upload sessions + +USAGE: + opencloud storage-users uploads sessions [command options] + +OPTIONS: + --id value filter sessions by upload session id (default: unset) + --processing filter sessions by processing status (default: unset) + --expired filter sessions by expired status (default: unset) + --has-virus filter sessions by virus scan result (default: unset) + --json output as json (default: false) + --restart send restart event for all listed sessions (default: false) + --resume send resume event for all listed sessions (default: false) + --clean remove uploads (default: false) + --help, -h show help +``` + +This will always output a list of uploads that match the criteria. See Command Examples section. + +Some additional information on returned information: + - `Offset` is the amount of bytes the server has already received. If `Offset` == `Size` the server has reveived all bytes of the upload. + - `Processing` indicates if the uploaded file is currently going through postprocessing. + - `Scan Date` and `Scan Result` indicate the scanning status. If `Scan Date` is set and `Scan Result` is empty the file is not virus infected. + +#### Command Examples + +Command to list ongoing upload sessions + +```bash +opencloud storage-users uploads sessions --expired=false --processing=false +``` + +```plaintext +Not expired sessions: ++--------------------------------------+--------------------------------------+---------+--------+------+--------------------------------------+--------------------------------------+---------------------------+------------+---------------------------+-----------------------+ +| Space | Upload Id | Name | Offset | Size | Executant | Owner | Expires | Processing | Scan Date | Scan Result | ++--------------------------------------+--------------------------------------+---------+--------+------+--------------------------------------+--------------------------------------+---------------------------+------------+---------------------------+-----------------------+ +| f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | 5e387954-7313-4223-a904-bf996da6ec0b | foo.txt | 0 | 1234 | f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | 2024-01-26T13:04:31+01:00 | false | 2024-04-24T11:24:14+02:00 | infected: virus A | +| f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | f066244d-97b2-48e7-a30d-b40fcb60cec6 | bar.txt | 0 | 4321 | f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c | 2024-01-26T13:18:47+01:00 | false | 2024-04-24T14:38:29+02:00 | | ++--------------------------------------+--------------------------------------+---------+--------+------+--------------------------------------+--------------------------------------+---------------------------+------------+---------------------------+-----------------------+ +``` + +The sessions command can also output json + +```bash +opencloud storage-users uploads sessions --expired=false --processing=false --json +``` + +```json +{"id":"5e387954-7313-4223-a904-bf996da6ec0b","space":"f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c","filename":"foo.txt","offset":0,"size":1234,"executant":{"idp":"https://cloud.opencloud.test","opaque_id":"f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c"},"spaceowner":{"opaque_id":"f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c"},"expires":"2024-01-26T13:04:31+01:00","processing":false, "scanDate": "2024-04-24T11:24:14+02:00", "scanResult": "infected: virus A"} +{"id":"f066244d-97b2-48e7-a30d-b40fcb60cec6","space":"f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c","filename":"bar.txt","offset":0,"size":4321,"executant":{"idp":"https://cloud.opencloud.test","opaque_id":"f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c"},"spaceowner":{"opaque_id":"f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c"},"expires":"2024-01-26T13:18:47+01:00","processing":false, "scanDate": "2024-04-24T14:38:29+02:00", "scanResult": ""} +``` + +The sessions command can also clear and restart/resume uploads. The output is the same as if run without `--clean` or `--restart` flag. +Note: It is recommended to run to command first without the `--clean` (`--processing`) flag to double check which uploads get cleaned (restarted/resumed). + +```bash +# cleans all expired uploads regardless of processing and virus state. +opencloud storage-users uploads sessions --expired=true --clean + +# resumes all uploads that are processing and are not virus infected +opencloud storage-users uploads sessions --processing=false --has-virus=false --resume +``` + +### Manage Trash-Bin Items + +This command set provides commands to get an overview of trash-bin items, restore items and purge old items of `personal` spaces and `project` spaces (spaces that have been created manually). `trash-bin` commands require a `spaceID` as parameter. + +```bash +opencloud storage-users trash-bin +``` + +```plaintext +COMMANDS: + purge-expired Purge expired trash-bin items + list Print a list of all trash-bin items of a space. + restore-all Restore all trash-bin items for a space. + restore Restore a trash-bin item by ID. +``` + +#### Purge Expired + +* Purge all expired items from the trash-bin. + ```bash + opencloud storage-users trash-bin purge-expired + ``` + +The behaviour of the `purge-expired` command can be configured by using the following environment variables. + +* `STORAGE_USERS_PURGE_TRASH_BIN_USER_ID`\ +Used to obtain space trash-bin information and takes the system admin user as the default which is the `OC_ADMIN_USER_ID` but can be set individually. It should be noted, that the `OC_ADMIN_USER_ID` is only assigned automatically when using the single binary deployment and must be manually assigned in all other deployments. The command only considers spaces to which the assigned user has access and delete permission. + +* `STORAGE_USERS_PURGE_TRASH_BIN_PERSONAL_DELETE_BEFORE`\ +Has a default value of `720h` which equals `30 days`. This means, the command will delete all files older than `30 days`. The value is human-readable. A value of `0` is equivalent to disable and prevents the deletion of `personal space` trash-bin files. + +* `STORAGE_USERS_PURGE_TRASH_BIN_PROJECT_DELETE_BEFORE`\ +Has a default value of `720h` which equals `30 days`. This means, the command will delete all files older than `30 days`. The value is human-readable. A value of `0` is equivalent to disable and prevents the deletion of `project space` trash-bin files. + +#### List and Restore Trash-Bins Items + +Restoring is possible only to the original location. The personal or project `spaceID` is required for the items to be restored. To authenticate the CLI tool use: + +```bash +OC_SERVICE_ACCOUNT_SECRET= +OC_SERVICE_ACCOUNT_ID= +``` + +The `storage-users` CLI tool uses the default address to establish the connection to the `gateway` service. If the connection fails, check the `GATEWAY_GRPC_ADDR` configuration from your `gateway` service and set the same address to the `storage-users` variable `STORAGE_USERS_GATEWAY_GRPC_ADDR` or globally with `OC_GATEWAY_GRPC_ADDR`. + +* Export the gateway address if your configuration differs from the default + ```bash + export STORAGE_USERS_GATEWAY_GRPC_ADDR=127.0.0.1:9142 + ``` + +* Print a list of all trash-bin items of a space + ```bash + opencloud storage-users trash-bin list [command options] ['spaceID' required] + ``` + +The restore option defines the behavior for an item to be restored, when the item name already exists in the target space. Supported options are: `skip`, `replace` and `keep-both`. The default value is `skip`. + +When the CLI tool restores the item with the `replace` option, the existing item will be moved to a trash-bin. When the CLI tool restores the item with the `keep-both` option and the designated item already exists, the name of the restored item will be changed by adding a numeric suffix in parentheses. The variable `STORAGE_USERS_CLI_MAX_ATTEMPTS_RENAME_FILE` defines a maximum number of attempts to rename an item. + +* Restore all trash-bin items for a space + ```bash + opencloud storage-users trash-bin restore-all [command options] ['spaceID' required] + ``` + +* Restore a trash-bin item by ID + ```bash + opencloud storage-users trash-bin restore [command options] ['spaceID' required] ['itemID' required] + ``` + +## Caching + +The `storage-users` service caches stat, metadata and uuids of files and folders via the configured store in `STORAGE_USERS_FILEMETADATA_CACHE_STORE` and `STORAGE_USERS_ID_CACHE_STORE`. Possible stores are: + - `memory`: Basic in-memory store and the default. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails.yaml new file mode 100644 index 00000000..9f722877 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails.yaml @@ -0,0 +1,63 @@ +# Autogenerated +# Filename: thumbnails.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9189 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9185 + tls: null + max_concurrent_requests: 0 +http: + addr: 127.0.0.1:9186 + tls: + enabled: false + cert: "" + key: "" + root: /thumbnails + cors: + allow_origins: + - '*' + allow_methods: + - GET + - POST + - PUT + - PATCH + - DELETE + - OPTIONS + allow_headers: + - Authorization + - Origin + - Content-Type + - Accept + - X-Requested-With + - X-Request-Id + - Cache-Control + allow_credentials: true +grpc_client_tls: null +thumbnail: + resolutions: + - 16x16 + - 32x32 + - 64x64 + - 128x128 + - 1080x1920 + - 1920x1080 + - 2160x3840 + - 3840x2160 + - 4320x7680 + - 7680x4320 + filesystem_storage: + root_directory: /root/.opencloud/thumbnails + webdav_allow_insecure: false + cs3_allow_insecure: false + reva_gateway: eu.opencloud.api.gateway + font_map_file: "" + transfer_secret: "" + data_endpoint: http://127.0.0.1:9186/thumbnails/data + max_input_width: 7680 + max_input_height: 7680 + max_input_image_file_size: 50MB diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_configvars.mdx new file mode 100644 index 00000000..bddb3793 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_configvars.mdx @@ -0,0 +1,31 @@ +Environment variables for the **thumbnails** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`THUMBNAILS_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`THUMBNAILS_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9189`| +|`THUMBNAILS_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`THUMBNAILS_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`THUMBNAILS_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`THUMBNAILS_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9185`| +|`THUMBNAILS_MAX_CONCURRENT_REQUESTS`| 1.0.0 |int|`Number of maximum concurrent thumbnail requests. Default is 0 which is unlimited.`|`0`| +|`THUMBNAILS_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9186`| +|`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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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.`|``| +|`THUMBNAILS_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/thumbnails`| +|`OC_CORS_ALLOW_ORIGINS`
`THUMBNAILS_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_CORS_ALLOW_METHODS`
`THUMBNAILS_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`
`THUMBNAILS_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 Cache-Control]`| +|`OC_CORS_ALLOW_CREDENTIALS`
`THUMBNAILS_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`| +|`THUMBNAILS_RESOLUTIONS`| 1.0.0 |[]string|`The supported list of target resolutions in the format WidthxHeight like 32x32. You can define any resolution as required. See the Environment Variable Types description for more details.`|`[16x16 32x32 64x64 128x128 1080x1920 1920x1080 2160x3840 3840x2160 4320x7680 7680x4320]`| +|`THUMBNAILS_FILESYSTEMSTORAGE_ROOT`| 1.0.0 |string|`The directory where the filesystem storage will store the thumbnails. If not defined, the root directory derives from $OC_BASE_DATA_PATH/thumbnails.`|`/root/.opencloud/thumbnails`| +|`OC_INSECURE`
`THUMBNAILS_WEBDAVSOURCE_INSECURE`| 1.0.0 |bool|`Ignore untrusted SSL certificates when connecting to the webdav source.`|`false`| +|`OC_INSECURE`
`THUMBNAILS_CS3SOURCE_INSECURE`| 1.0.0 |bool|`Ignore untrusted SSL certificates when connecting to the CS3 source.`|`false`| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`CS3 gateway used to look up user metadata`|`eu.opencloud.api.gateway`| +|`THUMBNAILS_TXT_FONTMAP_FILE`| 1.0.0 |string|`The path to a font file for txt thumbnails.`|``| +|`THUMBNAILS_TRANSFER_TOKEN`| 1.0.0 |string|`The secret to sign JWT to download the actual thumbnail file.`|``| +|`THUMBNAILS_DATA_ENDPOINT`| 1.0.0 |string|`The HTTP endpoint where the actual thumbnail file can be downloaded.`|`http://127.0.0.1:9186/thumbnails/data`| +|`THUMBNAILS_MAX_INPUT_WIDTH`| 1.0.0 |int|`The maximum width of an input image which is being processed.`|`7680`| +|`THUMBNAILS_MAX_INPUT_HEIGHT`| 1.0.0 |int|`The maximum height of an input image which is being processed.`|`7680`| +|`THUMBNAILS_MAX_INPUT_IMAGE_FILE_SIZE`| 1.0.0 |string|`The maximum file size of an input image which is being processed. Usable common abbreviations: [KB, KiB, MB, MiB, GB, GiB, TB, TiB, PB, PiB, EB, EiB], example: 2GB.`|`50MB`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_readme.mdx new file mode 100755 index 00000000..37ccaa7e --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/thumbnails_readme.mdx @@ -0,0 +1,152 @@ +--- +title: Thumbnails +date: 2026-01-15T10:35:01.395535425Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/thumbnails +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The thumbnails service provides methods to generate thumbnails for various files and resolutions based on requests. It retrieves the sources at the location where the user files are stored and saves the thumbnails where system files are stored. Those locations have defaults but can be manually defined via environment variables. + + +## Table of Contents + +* [File Locations Overview](#file-locations-overview) +* [Thumbnail Location](#thumbnail-location) +* [Thumbnail Source File Types](#thumbnail-source-file-types) +* [Thumbnail Target File Types](#thumbnail-target-file-types) +* [Thumbnail Query String Parameters](#thumbnail-query-string-parameters) +* [Thumbnail Resolution](#thumbnail-resolution) +* [Thumbnail Processors](#thumbnail-processors) +* [Deleting Thumbnails](#deleting-thumbnails) +* [Memory Considerations](#memory-considerations) +* [Thumbnails and SecureView](#thumbnails-and-secureview) +* [Using libvips for Thumbnail Generation](#using-libvips-for-thumbnail-generation) + +## File Locations Overview + +The relevant environment variables defining file locations are: + +- (1) `OC_BASE_DATA_PATH` +- (2) `STORAGE_USERS_DECOMPOSED_ROOT` +- (3) `THUMBNAILS_FILESYSTEMSTORAGE_ROOT` + +(1) ... Having a default set by the OpenCloud code, but if defined, used as base path for other services. +(2) ... Source files, defaults to (1) plus path component, but can be freely defined if required. +(3) ... Target files, defaults to (1) plus path component, but can be freely defined if required. + +For details and defaults for these environment variables see the OpenCloud admin documentation. + +## Thumbnail Location + +It may be beneficial to define the location of the thumbnails to be other than the default (with system files). This is due the fact that storing thumbnails can consume a lot of space over time which not necessarily needs to reside on the same partition or mount or expensive drives. + +## Thumbnail Source File Types + +Thumbnails can be generated from the following source file types: + +- png +- jpg +- gif +- tiff +- bmp +- txt + +The thumbnail service retrieves source files using the information provided by the backend. The Linux backend identifies source files usually based on the extension. + +If a file type was not properly assigned or the type identification failed, thumbnail generation will fail and an error will be logged. + +## Thumbnail Target File Types + +Thumbnails can either be generated as `png`, `jpg` or `gif` files. These types are hardcoded and no other types can be requested. A requestor, like another service or a client, can request one of the available types to be generated. If more than one type is required, each type must be requested individually. + +## Thumbnail Query String Parameters + +Clients can request thumbnail previews for files by adding `?preview=1` to the file URL. Requests for files with no thumbnail available respond with HTTP status `404`. + +The following query parameters are supported: + +| Parameter | Required | Default Value | Description | +|-----------|----------|------------------------------------------------------|---------------------------------------------------------------------------------| +| preview | YES | 1 | generates preview | +| x | YES | first x-value configured in `THUMBNAILS_RESOLUTIONS` | horizontal target size | +| y | YES | first y-value configured in `THUMBNAILS_RESOLUTIONS` | vertical target size | +| scalingup | NO | 0 | prevents up-scaling of small images | +| a | NO | 1 | aspect ratio | +| c | NO | Caching string | Clients should send the etag, so they get a fresh thumbnail after a file change | +| processor | NO | `resize` for gifs and `thumbnail` for all others | preferred thumbnail processor | + +## Thumbnail Resolution + +Various resolutions can be defined via `THUMBNAILS_RESOLUTIONS`. A requestor can request any arbitrary resolution and the thumbnail service will use the one closest to the requested resolution. If more than one resolution is required, each resolution must be requested individually. + +Example: + +Requested: 18x12\ +Available: 30x20, 15x10, 9x6\ +Returned: 15x10 + +## Thumbnail Processors + +Normally, an image might get cropped when creating a preview, depending on the aspect ratio of the original image. This can have negative +impacts on previews as only a part of the image will be shown. When using an _optional_ processor in the request, cropping can be avoided by defining on how the preview image generation will be done. The following processors are available: + +* `resize` resizes the image to the specified width and height and returns the transformed image. If one of width or height is 0, the image aspect ratio is preserved. +* `fit` scales down the image to fit the specified maximum width and height and returns the transformed image. +* `fill`: creates an image with the specified dimensions and fills it with the scaled source image. To achieve the correct aspect ratio without stretching, the source image will be cropped. +* `thumbnail` scales the image up or down, crops it to the specified width and height and returns the transformed image. + +To apply one of those, a query parameter has to be added to the request, like `?processor=fit`. If no query parameter or processor is added, the default behaviour applies which is `resize` for gifs and `thumbnail` for all others. + +## Deleting Thumbnails + +As of now, there is no automated thumbnail deletion. This is especially true when a source file gets deleted or moved. This situation will be solved at a later stage. For the time being, if you run short on physical thumbnails space, you have to manually delete the thumbnail store to free space. Thumbnails will then be recreated on request. + +## Memory Considerations + +Since source files need to be loaded into memory when generating thumbnails, large source files could potentially crash this service if there is insufficient memory available. For bigger instances when using container orchestration deployment methods, this service can be dedicated to its own server(s) with more memory. +To have more control over memory (and CPU) consumption the maximum number of concurrent requests can be limited by setting the environment variable `THUMBNAILS_MAX_CONCURRENT_REQUESTS`. The default value is 0 which does not apply any restrictions to the number of concurrent requests. As soon as the number of concurrent requests is reached any further request will be responded with `429/Too Many Requests` and the client can retry at a later point in time. + +## Thumbnails and SecureView + +If a resource is shared using SecureView, the share reciever will get a 403 (forbidden) response when requesting a thumbnail. The requesting client needs to decide what to show and usually a placeholder thumbnail is used. + +## Using libvips for Thumbnail Generation + +To improve performance and to support a wider range of images formats, the thumbnails service is able to utilize the [libvips library](https://www.libvips.org/) for thumbnail generation. Support for libvips needs to be +enabled at buildtime and has a couple of implications: + +* With libvips support enabled, it is not possible to create a statically linked OpenCloud binary. +* Therefore, the libvips shared libraries need to be available at runtime in the same release that was used to build the OpenCloud binary. +* When using the OpenCloud docker images, the libvips shared libraries are included in the image and are correctly embedded. + +Support of libvips is disabled by default. To enable it, make sure libvips and its buildtime dependencies are installed in your build environment. For macOS users, add the build time dependencies via: + +```shell +brew install vips pkg-config +export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig" +``` + +Then you just need to set the `ENABLE_VIPS` variable on the `make` command: + +```shell +make -C opencloud build ENABLE_VIPS=1 +``` + +Or include the `enable_vips` build tag in the `go build` command: + +```shell +go build -tags enable_vips -o opencloud -o bin/opencloud ./cmd/opencloud +``` + +When building a docker image using the Dockerfile in the top-level directory of OpenCloud, libvips support is enabled and the libvips shared libraries are included +in the resulting docker image. + + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog.yaml new file mode 100644 index 00000000..8c6d40e2 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog.yaml @@ -0,0 +1,58 @@ +# Autogenerated +# Filename: userlog.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9214 + token: "" + pprof: false + zpages: false +http: + addr: 127.0.0.1:9210 + root: / + cors: + allow_origins: + - '*' + allow_methods: + - GET + allow_headers: + - Authorization + - Origin + - Content-Type + - Accept + - X-Requested-With + - X-Request-Id + - Ocs-Apirequest + allow_credentials: true + tls: + enabled: false + cert: "" + key: "" +grpc_client_tls: null +token_manager: + jwt_secret: "" +reva_gateway: eu.opencloud.api.gateway +translation_path: "" +default_language: "" +events: + endpoint: 127.0.0.1:9233 + cluster: opencloud-cluster + tls_insecure: false + tls_root_ca_certificate: "" + enable_tls: false + username: "" + password: "" +max_concurrency: 1 +persistence: + store: memory + nodes: [] + database: userlog + table: events + ttl: 336h0m0s + username: "" + password: "" +disable_sse: false +global_notifications_secret: "" +service_account: + service_account_id: "" + service_account_secret: "" diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_configvars.mdx new file mode 100644 index 00000000..ee43f221 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_configvars.mdx @@ -0,0 +1,41 @@ +Environment variables for the **userlog** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`USERLOG_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`USERLOG_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9214`| +|`USERLOG_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`USERLOG_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`USERLOG_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`USERLOG_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9210`| +|`USERLOG_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/`| +|`OC_CORS_ALLOW_ORIGINS`
`USERLOG_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_CORS_ALLOW_METHODS`
`USERLOG_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_HEADERS`
`USERLOG_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_CREDENTIALS`
`USERLOG_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_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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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_JWT_SECRET`
`USERLOG_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`CS3 gateway used to look up user metadata`|`eu.opencloud.api.gateway`| +|`OC_TRANSLATION_PATH`
`USERLOG_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_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_EVENTS_ENDPOINT`
`USERLOG_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_CLUSTER`
`USERLOG_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_INSECURE`
`OC_EVENTS_TLS_INSECURE`
`USERLOG_EVENTS_TLS_INSECURE`| 1.0.0 |bool|`Whether to verify the server TLS certificates.`|`false`| +|`OC_EVENTS_TLS_ROOT_CA_CERTIFICATE`
`USERLOG_EVENTS_TLS_ROOT_CA_CERTIFICATE`| 1.0.0 |string|`The root CA certificate used to validate the server's TLS certificate. If provided NOTIFICATIONS_EVENTS_TLS_INSECURE will be seen as false.`|``| +|`OC_EVENTS_ENABLE_TLS`
`USERLOG_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_AUTH_USERNAME`
`USERLOG_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_AUTH_PASSWORD`
`USERLOG_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_MAX_CONCURRENCY`
`USERLOG_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_PERSISTENT_STORE`
`USERLOG_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.`|`memory`| +|`OC_PERSISTENT_STORE_NODES`
`USERLOG_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.`|`[]`| +|`USERLOG_STORE_DATABASE`| 1.0.0 |string|`The database name the configured store should use.`|`userlog`| +|`USERLOG_STORE_TABLE`| 1.0.0 |string|`The database table the store should use.`|`events`| +|`OC_PERSISTENT_STORE_TTL`
`USERLOG_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.`|`336h0m0s`| +|`OC_PERSISTENT_STORE_AUTH_USERNAME`
`USERLOG_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_AUTH_PASSWORD`
`USERLOG_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_DISABLE_SSE,USERLOG_DISABLE_SSE`| 1.0.0 |bool|`Disables server-sent events (sse). When disabled, clients will no longer receive sse notifications.`|`false`| +|`USERLOG_GLOBAL_NOTIFICATIONS_SECRET`| 1.0.0 |string|`The secret to secure the global notifications endpoint. Only system admins and users knowing that secret can call the global notifications POST/DELETE endpoints.`|``| +|`OC_SERVICE_ACCOUNT_ID`
`USERLOG_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`
`USERLOG_SERVICE_ACCOUNT_SECRET`| 1.0.0 |string|`The service account secret.`|``| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_readme.mdx new file mode 100755 index 00000000..3bba14ff --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/userlog_readme.mdx @@ -0,0 +1,115 @@ +--- +title: Userlog +date: 2026-01-15T10:35:01.395702785Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/userlog +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `userlog` service is a mediator between the `eventhistory` service and clients who want to be informed about user related events. It provides an API to retrieve those. + + +## Table of Contents + +* [The Log Service Ecosystem](#the-log-service-ecosystem) +* [Prerequisites](#prerequisites) +* [Storing](#storing) +* [Configuring](#configuring) +* [Retrieving](#retrieving) +* [Posting](#posting) + * [Authentication](#authentication) + * [Deprovisioning](#deprovisioning) +* [Deleting](#deleting) +* [Translations](#translations) + * [Translation Rules](#translation-rules) +* [Default Language](#default-language) + +## The Log Service Ecosystem + +Log services like the `userlog`, `clientlog` and `sse` are responsible for composing notifications for a certain audience. + - The `userlog` service translates and adjusts messages to be human readable. + - The `clientlog` service composes machine readable messages, so clients can act without the need to query the server. + - The `sse` service is only responsible for sending these messages. It does not care about their form or language. + +## Prerequisites + +Running the `userlog` service without running the `eventhistory` service is not possible. + +## Storing + +The `userlog` service persists information via the configured store in `USERLOG_STORE`. Possible stores are: + - `memory`: Basic in-memory store and the default. + - `redis-sentinel`: Stores data in a configured Redis Sentinel cluster. + - `nats-js-kv`: Stores data using key-value-store feature of [nats jetstream](https://docs.nats.io/nats-concepts/jetstream/key-value-store) + - `noop`: Stores nothing. Useful for testing. Not recommended in production environments. + +Other store types may work but are not supported currently. + +Note: The service can only be scaled if not using `memory` store and the stores are configured identically over all instances! + +Note that if you have used one of the deprecated stores, you should reconfigure to one of the supported ones as the deprecated stores will be removed in a later version. + +Store specific notes: + - When using `redis-sentinel`, the Redis master to use is configured via e.g. `OC_CACHE_STORE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. + - When using `nats-js-kv` it is recommended to set `OC_CACHE_STORE_NODES` to the same value as `OC_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. + - When using the `nats-js-kv` store, it is possible to set `OC_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. + +## Configuring + +For the time being, the configuration which user related events are of interest is hardcoded and cannot be changed. + +## Retrieving + +The `userlog` service provides an API to retrieve configured events. For now, this API is mostly following the [oc10 notification GET API](https://doc.owncloud.com/server/next/developer_manual/core/apis/ocs-notification-endpoint-v1.html#get-user-notifications). + +## Posting + +The userlog service is able to store global messages that will be displayed in the Web UI to all users. If a user deletes the message in the Web UI, it reappears on reload. Global messages use the endpoint `/ocs/v2.php/apps/notifications/api/v1/notifications/global` and are activated by sending a `POST` request. Note that sending another `POST` request of the same type overwrites the previous one. For the time being, only the type `deprovision` is supported. + +### Authentication + +`POST` and `DELETE` endpoints provide notifications to all users. Therefore only certain users can configure them. Two authentication methods for this endpoint are provided. Users with the `admin` role can always access these endpoints. Additionally, a static secret via the `USERLOG_GLOBAL_NOTIFICATIONS_SECRET` can be defined to enable access for users knowing this secret, which has to be sent with the header containing the request. + +### Deprovisioning + +Deprovision messages announce a deprovision text including a deprovision date of the instance to all users. With this message, users get informed that the instance will be shut down and deprovisioned and no further access to their data is possible past the given date. This implies that users must download their data before the given date. The text shown to users refers to this information. Note that the task to deprovision the instance does not depend on the message. The text of the message can be translated according to the translation settings, see section [Translations](#translations). The endpoint only expects a `deprovision_date` parameter in the `POST` request body as the final text is assembled automatically. The string hast to be in `RFC3339` format, however, this format can be changed by using `deprovision_date_format`. See the [go time formating](https://pkg.go.dev/time#pkg-constants) for more details. + +## Deleting + +To delete events for an user, use a `DELETE` request to `ocs/v2.php/apps/notifications/api/v1/notifications` containing the IDs to delete. + +Sending a `DELETE` request to the `ocs/v2.php/apps/notifications/api/v1/notifications/global` endpoint to remove a global message is a restricted action, see the [Authentication](#authentication) section for more details.) + +## Translations + +The `userlog` service has embedded translations sourced via transifex to provide a basic set of translated languages. These embedded translations are available for all deployment scenarios. In addition, the service supports custom translations, though it is currently not possible to just add custom translations to embedded ones. If custom translations are configured, the embedded ones are not used. To configure custom translations, the `USERLOG_TRANSLATION_PATH` environment variable needs to point to a base folder that will contain the translation files. This path must be available from all instances of the userlog service, a shared storage is recommended. Translation files must be of type [.po](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html#PO-Files) or [.mo](https://www.gnu.org/software/gettext/manual/html_node/Binaries.html). For each language, the filename needs to be `userlog.po` (or `userlog.mo`) and stored in a folder structure defining the language code. In general the path/name pattern for a translation file needs to be: + +```text +{USERLOG_TRANSLATION_PATH}/{language-code}/LC_MESSAGES/userlog.po +``` + +The language code pattern is composed of `language[_territory]` where `language` is the base language and `_territory` is optional and defines a country. + +For example, for the language `de`, one needs to place the corresponding translation files to `{USERLOG_TRANSLATION_PATH}/de_DE/LC_MESSAGES/userlog.po`. + + + +Important: For the time being, the embedded OpenCloud Web frontend only supports the main language code but does not handle any territory. When strings are available in the language code `language_territory`, the web frontend does not see it as it only requests `language`. In consequence, any translations made must exist in the requested `language` to avoid a fallback to the default. + +### Translation Rules + +* If a requested language code is not available, the service tries to fall back to the base language if available. For example, if the requested language-code `de_DE` is not available, the service tries to fall back to translations in the `de` folder. +* If the base language `de` is also not available, the service falls back to the system's default English (`en`), +which is the source of the texts provided by the code. + +## Default Language + +The default language can be defined via the `OC_DEFAULT_LANGUAGE` environment variable. See the `settings` service for a detailed description. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users.yaml new file mode 100644 index 00000000..82efb1af --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users.yaml @@ -0,0 +1,68 @@ +# Autogenerated +# Filename: users.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9145 + token: "" + pprof: false + zpages: false +grpc: + addr: 127.0.0.1:9144 + tls: null + protocol: tcp +token_manager: + jwt_secret: "" +reva: + address: eu.opencloud.api.gateway + tls: + mode: "" + cacert: "" +skip_user_groups_in_token: false +driver: ldap +drivers: + ldap: + uri: ldaps://localhost:9235 + ca_cert: /root/.opencloud/idm/ldap.crt + insecure: false + bind_dn: uid=reva,ou=sysusers,o=libregraph-idm + bind_password: "" + user_base_dn: ou=users,o=libregraph-idm + group_base_dn: ou=groups,o=libregraph-idm + user_scope: sub + group_scope: sub + user_substring_filter_type: any + user_filter: "" + group_filter: "" + user_object_class: inetOrgPerson + group_object_class: groupOfNames + idp: https://localhost:9200 + disable_user_mechanism: attribute + user_type_attribute: openCloudUserType + ldap_disabled_users_group_dn: cn=DisabledUsersGroup,ou=groups,o=libregraph-idm + user_schema: + id: openclouduuid + tenant_id: "" + id_is_octet_string: false + mail: mail + display_name: displayname + user_name: uid + user_enabled: openclouduserenabled + group_schema: + id: openclouduuid + id_is_octet_string: false + mail: mail + display_name: cn + group_name: cn + member: member + owncloudsql: + db_username: owncloud + db_password: secret + db_host: mysql + db_port: 3306 + db_name: owncloud + idp: https://localhost:9200 + nobody: 90 + join_username: false + join_owncloud_uuid: false + enable_medial_search: false diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_configvars.mdx new file mode 100644 index 00000000..1fe8ccc1 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_configvars.mdx @@ -0,0 +1,58 @@ +Environment variables for the **users** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`USERS_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`USERS_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9145`| +|`USERS_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`USERS_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`USERS_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`USERS_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`127.0.0.1:9144`| +|`OC_GRPC_PROTOCOL`
`USERS_GRPC_PROTOCOL`| 1.0.0 |string|`The transport protocol of the GPRC service.`|`tcp`| +|`OC_JWT_SECRET`
`USERS_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`The CS3 gateway endpoint.`|`eu.opencloud.api.gateway`| +|`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.`|``| +|`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.`|``| +|`USERS_SKIP_USER_GROUPS_IN_TOKEN`| 1.0.0 |bool|`Disables the loading of user's group memberships from the reva access token.`|`false`| +|`USERS_DRIVER`| 1.0.0 |string|`The driver which should be used by the users service. Supported values are 'ldap' and 'owncloudsql'.`|`ldap`| +|`OC_LDAP_URI`
`USERS_LDAP_URI`| 1.0.0 |string|`URI of the LDAP Server to connect to. Supported URI schemes are 'ldaps://' and 'ldap://'`|`ldaps://localhost:9235`| +|`OC_LDAP_CACERT`
`USERS_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.`|`/root/.opencloud/idm/ldap.crt`| +|`OC_LDAP_INSECURE`
`USERS_LDAP_INSECURE`| 1.0.0 |bool|`Disable TLS certificate validation for the LDAP connections. Do not set this in production environments.`|`false`| +|`OC_LDAP_BIND_DN`
`USERS_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`
`USERS_LDAP_BIND_PASSWORD`| 1.0.0 |string|`Password to use for authenticating the 'bind_dn'.`|``| +|`OC_LDAP_USER_BASE_DN`
`USERS_LDAP_USER_BASE_DN`| 1.0.0 |string|`Search base DN for looking up LDAP users.`|`ou=users,o=libregraph-idm`| +|`OC_LDAP_GROUP_BASE_DN`
`USERS_LDAP_GROUP_BASE_DN`| 1.0.0 |string|`Search base DN for looking up LDAP groups.`|`ou=groups,o=libregraph-idm`| +|`OC_LDAP_USER_SCOPE`
`USERS_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_GROUP_SCOPE`
`USERS_LDAP_GROUP_SCOPE`| 1.0.0 |string|`LDAP search scope to use when looking up groups. Supported values are 'base', 'one' and 'sub'.`|`sub`| +|`LDAP_USER_SUBSTRING_FILTER_TYPE`
`USERS_LDAP_USER_SUBSTRING_FILTER_TYPE`| 1.0.0 |string|`Type of substring search filter to use for substring searches for users. Possible values: 'initial' for doing prefix only searches, 'final' for doing suffix only searches or 'any' for doing full substring searches`|`any`| +|`OC_LDAP_USER_FILTER`
`USERS_LDAP_USER_FILTER`| 1.0.0 |string|`LDAP filter to add to the default filters for user search like '(objectclass=openCloudUser)'.`|``| +|`OC_LDAP_GROUP_FILTER`
`USERS_LDAP_GROUP_FILTER`| 1.0.0 |string|`LDAP filter to add to the default filters for group searches.`|``| +|`OC_LDAP_USER_OBJECTCLASS`
`USERS_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_GROUP_OBJECTCLASS`
`USERS_LDAP_GROUP_OBJECTCLASS`| 1.0.0 |string|`The object class to use for groups in the default group search filter like 'groupOfNames'.`|`groupOfNames`| +|`OC_URL`
`OC_OIDC_ISSUER`
`USERS_IDP_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_LDAP_DISABLE_USER_MECHANISM`
`USERS_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_USER_SCHEMA_USER_TYPE`
`USERS_LDAP_USER_TYPE_ATTRIBUTE`| 1.0.0 |string|`LDAP Attribute to distinguish between 'Member' and 'Guest' users. Default is 'openCloudUserType'.`|`openCloudUserType`| +|`OC_LDAP_DISABLED_USERS_GROUP_DN`
`USERS_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_USER_SCHEMA_ID`
`USERS_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_TENANT_ID`
`USERS_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_ID_IS_OCTETSTRING`
`USERS_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`
`USERS_LDAP_USER_SCHEMA_MAIL`| 1.0.0 |string|`LDAP Attribute to use for the email address of users.`|`mail`| +|`OC_LDAP_USER_SCHEMA_DISPLAYNAME`
`USERS_LDAP_USER_SCHEMA_DISPLAYNAME`| 1.0.0 |string|`LDAP Attribute to use for the displayname of users.`|`displayname`| +|`OC_LDAP_USER_SCHEMA_USERNAME`
`USERS_LDAP_USER_SCHEMA_USERNAME`| 1.0.0 |string|`LDAP Attribute to use for username of users.`|`uid`| +|`OC_LDAP_USER_ENABLED_ATTRIBUTE`
`USERS_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_GROUP_SCHEMA_ID`
`USERS_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`
`USERS_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`
`USERS_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_DISPLAYNAME`
`USERS_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`
`USERS_LDAP_GROUP_SCHEMA_GROUPNAME`| 1.0.0 |string|`LDAP Attribute to use for the name of groups.`|`cn`| +|`OC_LDAP_GROUP_SCHEMA_MEMBER`
`USERS_LDAP_GROUP_SCHEMA_MEMBER`| 1.0.0 |string|`LDAP Attribute that is used for group members.`|`member`| +|`USERS_OWNCLOUDSQL_DB_USERNAME`| 1.0.0 |string|`Database user to use for authenticating with the owncloud database.`|`owncloud`| +|`USERS_OWNCLOUDSQL_DB_PASSWORD`| 1.0.0 |string|`Password for the database user.`|`secret`| +|`USERS_OWNCLOUDSQL_DB_HOST`| 1.0.0 |string|`Hostname of the database server.`|`mysql`| +|`USERS_OWNCLOUDSQL_DB_PORT`| 1.0.0 |int|`Network port to use for the database connection.`|`3306`| +|`USERS_OWNCLOUDSQL_DB_NAME`| 1.0.0 |string|`Name of the owncloud database.`|`owncloud`| +|`USERS_OWNCLOUDSQL_IDP`| 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`| +|`USERS_OWNCLOUDSQL_NOBODY`| 1.0.0 |int64|`Fallback number if no numeric UID and GID properties are provided.`|`90`| +|`USERS_OWNCLOUDSQL_JOIN_USERNAME`| 1.0.0 |bool|`Join the user properties table to read usernames`|`false`| +|`USERS_OWNCLOUDSQL_JOIN_OWNCLOUD_UUID`| 1.0.0 |bool|`Join the user properties table to read user IDs.`|`false`| +|`USERS_OWNCLOUDSQL_ENABLE_MEDIAL_SEARCH`| 1.0.0 |bool|`Allow 'medial search' when searching for users instead of just doing a prefix search. This allows finding 'Alice' when searching for 'lic'.`|`false`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_readme.mdx new file mode 100755 index 00000000..d46b3973 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/users_readme.mdx @@ -0,0 +1,50 @@ +--- +title: Users +date: 2026-01-15T10:35:01.395921734Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/users +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The `users` service provides the CS3 Users API for OpenCloud. It is responsible for managing user information and authentication within the OpenCloud instance. + +This service implements the CS3 identity user provider interface, allowing other services to query and manage user accounts. It works as a backend provider for the `graph` service when using the CS3 backend mode. + + +## Table of Contents + +* [Backend Integration](#backend-integration) +* [API](#api) +* [Usage](#usage) +* [Scalability](#scalability) + +## Backend Integration + +The users service can work with different storage backends: +- LDAP integration through the graph service +- Direct CS3 API implementation + +When using the `graph` service with the CS3 backend (`GRAPH_IDENTITY_BACKEND=cs3`), the graph service queries user information through this service. + +## API + +The service provides CS3 gRPC APIs for: +- Listing users +- Getting user information +- Finding users by username, email, or ID + +## Usage + +The users service is only used internally by other OpenCloud services and not being accessed directly by clients. The `frontend`, `ocs`, and `graph` services translate HTTP API requests into CS3 API calls to this service. + +## Scalability + +Since the users service queries backend systems (like LDAP through the configured identity backend), it can be scaled horizontally without additional configuration when using stateless backends. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web.yaml new file mode 100644 index 00000000..861dcd39 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web.yaml @@ -0,0 +1,122 @@ +# Autogenerated +# Filename: web.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9104 + token: "" + pprof: false + zpages: false +http: + addr: 127.0.0.1:9100 + tls: + enabled: false + cert: "" + key: "" + root: / + cache_ttl: 604800 + cors: + allow_origins: + - https://localhost:9200 + allow_methods: + - OPTIONS + - HEAD + - GET + - PUT + - PATCH + - POST + - DELETE + - MKCOL + - PROPFIND + - PROPPATCH + - MOVE + - COPY + - REPORT + - SEARCH + allow_headers: + - Origin + - Accept + - Content-Type + - Depth + - Authorization + - Ocs-Apirequest + - If-None-Match + - If-Match + - Destination + - Overwrite + - X-Request-Id + - X-Requested-With + - Tus-Resumable + - Tus-Checksum-Algorithm + - Upload-Concat + - Upload-Length + - Upload-Metadata + - Upload-Defer-Length + - Upload-Expires + - Upload-Checksum + - Upload-Offset + - X-HTTP-Method-Override + allow_credentials: false +asset: + core_path: /root/.opencloud/web/assets/core + themes_path: /root/.opencloud/web/assets/themes + apps_path: /root/.opencloud/web/assets/apps +file: "" +web: + theme_server: https://localhost:9200 + theme_path: /themes/opencloud/theme.json + config: + server: https://localhost:9200 + oidc: + metadata_url: https://localhost:9200/.well-known/openid-configuration + authority: https://localhost:9200 + client_id: web + response_type: code + scope: openid profile email + post_logout_redirect_uri: "" + apps: + - files + - search + - text-editor + - pdf-viewer + - external + - admin-settings + - epub-reader + - preview + - app-store + applications: [] + external_apps: [] + options: + accountEditLink: null + disableFeedbackLink: false + feedbackLink: null + runningOnEos: false + cernFeatures: false + upload: null + editor: null + contextHelpersReadMore: true + logoutUrl: "" + loginUrl: "" + tokenStorageLocal: true + disabledExtensions: [] + embed: + enabled: "" + target: "" + messagesOrigin: "" + delegateAuthentication: false + delegateAuthenticationOrigin: "" + userListRequiresFilter: false + concurrentRequests: + resourceBatchActions: 0 + sse: 0 + shares: + create: 0 + list: 0 + defaultAppId: "" + styles: [] + scripts: [] + custom_translations: [] +apps: {} +token_manager: + jwt_secret: "" +gateway_addr: eu.opencloud.api.gateway diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_configvars.mdx new file mode 100644 index 00000000..e34d1bb8 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_configvars.mdx @@ -0,0 +1,52 @@ +Environment variables for the **web** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`WEB_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`WEB_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9104`| +|`WEB_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`WEB_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`WEB_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`WEB_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9100`| +|`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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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.`|``| +|`WEB_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/`| +|`WEB_CACHE_TTL`| 1.0.0 |int|`Cache policy in seconds for OpenCloud Web assets.`|`604800`| +|`OC_CORS_ALLOW_ORIGINS`
`WEB_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.`|`[https://localhost:9200]`| +|`OC_CORS_ALLOW_METHODS`
`WEB_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.`|`[OPTIONS HEAD GET PUT PATCH POST DELETE MKCOL PROPFIND PROPPATCH MOVE COPY REPORT SEARCH]`| +|`OC_CORS_ALLOW_HEADERS`
`WEB_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.`|`[Origin Accept Content-Type Depth Authorization Ocs-Apirequest If-None-Match If-Match Destination Overwrite X-Request-Id X-Requested-With Tus-Resumable Tus-Checksum-Algorithm Upload-Concat Upload-Length Upload-Metadata Upload-Defer-Length Upload-Expires Upload-Checksum Upload-Offset X-HTTP-Method-Override]`| +|`OC_CORS_ALLOW_CREDENTIALS`
`WEB_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.`|`false`| +|`WEB_ASSET_CORE_PATH`| 1.0.0 |string|`Serve OpenCloud Web assets from a path on the filesystem instead of the builtin assets. If not defined, the root directory derives from $OC_BASE_DATA_PATH/web/assets/core`|`/root/.opencloud/web/assets/core`| +|`OC_ASSET_THEMES_PATH`
`WEB_ASSET_THEMES_PATH`| 1.0.0 |string|`Serve OpenCloud themes from a path on the filesystem instead of the builtin assets. If not defined, the root directory derives from $OC_BASE_DATA_PATH/web/assets/themes`|`/root/.opencloud/web/assets/themes`| +|`WEB_ASSET_APPS_PATH`| 1.0.0 |string|`Serve OpenCloud Web apps assets from a path on the filesystem instead of the builtin assets. If not defined, the root directory derives from $OC_BASE_DATA_PATH/web/assets/apps`|`/root/.opencloud/web/assets/apps`| +|`WEB_UI_CONFIG_FILE`| 1.0.0 |string|`Read the OpenCloud Web json based configuration from this path/file. The config file takes precedence over WEB_OPTION_xxx environment variables. See the text description for more details.`|``| +|`OC_URL`
`WEB_UI_THEME_SERVER`| 1.0.0 |string|`Base URL to load themes from. Will be prepended to the theme path.`|`https://localhost:9200`| +|`WEB_UI_THEME_PATH`| 1.0.0 |string|`Path to the theme json file. Will be appended to the URL of the theme server.`|`/themes/opencloud/theme.json`| +|`OC_URL`
`WEB_UI_CONFIG_SERVER`| 1.0.0 |string|`URL, where the OpenCloud APIs are reachable for OpenCloud Web.`|`https://localhost:9200`| +|`WEB_OIDC_METADATA_URL`| 1.0.0 |string|`URL for the OIDC well-known configuration endpoint. Defaults to the OpenCloud API URL + '/.well-known/openid-configuration'.`|`https://localhost:9200/.well-known/openid-configuration`| +|`OC_URL`
`OC_OIDC_ISSUER`
`WEB_OIDC_AUTHORITY`| 1.0.0 |string|`URL of the OIDC issuer. It defaults to URL of the builtin IDP.`|`https://localhost:9200`| +|`OC_OIDC_CLIENT_ID`
`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_RESPONSE_TYPE`| 1.0.0 |string|`The OIDC response type to use for authentication.`|`code`| +|`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_POST_LOGOUT_REDIRECT_URI`| 1.0.0 |string|`This value needs to point to a valid and reachable web page. The web client will trigger a redirect to that page directly after the logout action. The default value is empty and redirects to the login page.`|``| +|`WEB_OPTION_DISABLE_FEEDBACK_LINK`| 1.0.0 |bool|`Set this option to 'true' to disable the feedback link in the top bar. Keeping it enabled by setting the value to 'false' or with the absence of the option, allows OpenCloud to get feedback from your user base through a dedicated survey website.`|`false`| +|`WEB_OPTION_RUNNING_ON_EOS`| 1.0.0 |bool|`Set this option to 'true' if running on an EOS storage backend (\https://eos-web.web.cern.ch/eos-web/) to enable its specific features. Defaults to 'false'.`|`false`| +|`WEB_OPTION_CONTEXTHELPERS_READ_MORE`| 1.0.0 |bool|`Specifies whether the 'Read more' link should be displayed or not.`|`true`| +|`WEB_OPTION_LOGOUT_URL`| 1.0.0 |string|`Adds a link to the user's profile page to point him to an external page, where he can manage his session and devices. This is helpful when an external IdP is used. This option is disabled by default.`|``| +|`WEB_OPTION_LOGIN_URL`| 1.0.0 |string|`Specifies the target URL to the login page. This is helpful when an external IdP is used. This option is disabled by default. Example URL like: \https://www.myidp.com/login.`|``| +|`WEB_OPTION_TOKEN_STORAGE_LOCAL`| 1.0.0 |bool|`Specifies whether the access token will be stored in the local storage when set to 'true' or in the session storage when set to 'false'. If stored in the local storage, login state will be persisted across multiple browser tabs, means no additional logins are required.`|`true`| +|`WEB_OPTION_DISABLED_EXTENSIONS`| 1.0.0 |[]string|`A list to disable specific Web extensions identified by their ID. The ID can e.g. be taken from the 'index.ts' file of the web extension. Example: 'com.github.opencloud-eu.web.files.search,com.github.opencloud-eu.web.files.print'. See the Environment Variable Types description for more details.`|`[]`| +|`WEB_OPTION_EMBED_ENABLED`| 1.0.0 |string|`Defines whether Web should be running in 'embed' mode. Setting this to 'true' will enable a stripped down version of Web with reduced functionality used to integrate Web into other applications like via iFrame. Setting it to 'false' or not setting it (default) will run Web as usual with all functionality enabled. See the text description for more details.`|``| +|`WEB_OPTION_EMBED_TARGET`| 1.0.0 |string|`Defines how Web is being integrated when running in 'embed' mode. Currently, the only supported options are '' (empty) and 'location'. With '' which is the default, Web will run regular as defined via the 'embed.enabled' config option. With 'location', Web will run embedded as location picker. Resource selection will be disabled and the selected resources array always includes the current folder as the only item. See the text description for more details.`|``| +|`WEB_OPTION_EMBED_MESSAGES_ORIGIN`| 1.0.0 |string|`Defines a URL under which Web can be integrated via iFrame in 'embed' mode. Note that setting this is mandatory when running Web in 'embed' mode. Use '*' as value to allow running the iFrame under any URL, although this is not recommended for security reasons. See the text description for more details.`|``| +|`WEB_OPTION_EMBED_DELEGATE_AUTHENTICATION`| 1.0.0 |bool|`Defines whether Web should require authentication to be done by the parent application when running in 'embed' mode. If set to 'true' Web will not try to authenticate the user on its own but will require an access token coming from the parent application. Defaults to being unset.`|`false`| +|`WEB_OPTION_EMBED_DELEGATE_AUTHENTICATION_ORIGIN`| 1.0.0 |string|`Defines the host to validate the message event origin against when running Web in 'embed' mode with delegated authentication. Defaults to event message origin validation being omitted, which is only recommended for development setups.`|``| +|`WEB_OPTION_USER_LIST_REQUIRES_FILTER`| 1.0.0 |bool|`Defines whether one or more filters must be set in order to list users in the Web admin settings. Set this option to 'true' if running in an environment with a lot of users and listing all users could slow down performance. Defaults to 'false'.`|`false`| +|`WEB_OPTION_CONCURRENT_REQUESTS_RESOURCE_BATCH_ACTIONS`| 1.0.0 |int|`Defines the maximum number of concurrent requests per file/folder/space batch action. Defaults to 4.`|`0`| +|`WEB_OPTION_CONCURRENT_REQUESTS_SSE`| 1.0.0 |int|`Defines the maximum number of concurrent requests in SSE event handlers. Defaults to 4.`|`0`| +|`WEB_OPTION_CONCURRENT_REQUESTS_SHARES_CREATE`| 1.0.0 |int|`Defines the maximum number of concurrent requests per sharing invite batch. Defaults to 4.`|`0`| +|`WEB_OPTION_CONCURRENT_REQUESTS_SHARES_LIST`| 1.0.0 |int|`Defines the maximum number of concurrent requests when loading individual share information inside listings. Defaults to 2.`|`0`| +|`WEB_OPTION_DEFAULT_APP_ID`| 4.0.0 |string|`Defines the entrypoint for the web ui.`|``| +|`OC_JWT_SECRET`
`WEB_JWT_SECRET`| 1.0.0 |string|`The secret to mint and validate jwt tokens.`|``| +|`WEB_GATEWAY_GRPC_ADDR`| 1.0.0 |string|`The bind address of the GRPC service.`|`eu.opencloud.api.gateway`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_readme.mdx new file mode 100755 index 00000000..070e4ea9 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/web_readme.mdx @@ -0,0 +1,206 @@ +--- +title: Web +date: 2026-01-15T10:35:01.396050844Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/web +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The web service embeds and serves the static files for the [OpenCloud Web Client](https://github.com/opencloud-eu/web). +Note that clients will respond with a connection error if the web service is not available. + +The web service also provides a minimal API for branding functionality like changing the logo shown. + + +## Table of Contents + +* [Custom Compiled Web Assets](#custom-compiled-web-assets) +* [Web UI Configuration](#web-ui-configuration) + * [Web UI Options](#web-ui-options) + * [Web UI Config File](#web-ui-config-file) + * [Embedding Web](#embedding-web) +* [Web Apps](#web-apps) + * [Loading Themes](#loading-themes) + * [Loading Applications](#loading-applications) + * [Application Structure](#application-structure) + * [Application Configuration](#application-configuration) + * [Using Custom Assets](#using-custom-assets) +* [Miscellaneous](#miscellaneous) + +## Custom Compiled Web Assets + +If you want to use your custom compiled web client assets instead of the embedded ones, +then you can do that by setting the `WEB_ASSET_CORE_PATH` variable to point to your compiled files. +See [OpenCloud Web / Getting Started](https://docs.opencloud.eu/clients/web/getting-started/) for more details. + +## Web UI Configuration + +* Single configuration settings of the embedded web UI can be defined via `WEB_OPTION_xxx` environment variables. +* A json based configuration file can be used via the `WEB_UI_CONFIG_FILE` environment variable. +* If a json based configuration file is used, these configurations take precedence over single options set. + +### Web UI Options + +Besides theming, the behavior of the web UI can be configured via options. See the environment variables `WEB_OPTION_xxx` +for more details. + +### Web UI Config File + +When defined via the `WEB_UI_CONFIG_FILE` environment variable, the configuration of the web UI can be made +with a [json based](https://github.com/opencloud-eu/web/tree/master/config) file. + +### Embedding Web + +Web can be consumed by another application in a stripped down version called “Embed mode”. +This mode is supposed to be used in the context of selecting or sharing resources. + +For more details see the developer documentation [OpenCloud Web / Embed Mode](https://docs.opencloud.eu/docs/dev/web/embed-mode). +See the environment variables: `WEB_OPTION_MODE` and `WEB_OPTION_EMBED_TARGET` to configure the embedded mode. + +## Web Apps + +The administrator of the environment is capable of providing custom web applications to the users. +This feature is useful for organizations that want to provide third party or custom apps to their users. + +It's important to note that the feature at the moment is only capable of providing static (js, mjs, e.g.) web applications +and does not support injection of dynamic web applications (custom dynamic backends). + +### Loading Themes + +Web themes are loaded, if added in the OpenCloud source code, at build-time from +`/services/web/assets/themes`. +This cannot be manipulated at runtime. + +Additionally, the administrator can provide custom themes by storing it in the path defined by the environment +variable `WEB_ASSET_THEMES_PATH`. + +With the theme root directory defined, the system needs to know which theme to use. +This can be done by setting the `WEB_UI_THEME_PATH` environment variable. + +The final theme is composed of the built-in and the custom theme provided by the +administrator via `WEB_ASSET_THEMES_PATH` and `WEB_UI_THEME_PATH`. + +For example, OpenCloud by default contains a built-in OpenCloud theme. +If the administrator provides a custom theme via the `WEB_ASSET_THEMES_PATH` directory like, +`WEB_ASSET_THEMES_PATH/opencloud/themes.json`, this one will be used instead of the built-in one. + +Some theme keys are mandatory, like the `common.shareRoles` settings. +Such mandatory keys are injected automatically at runtime if not provided. + +### Loading Applications + +Web applications are loaded, if added in the OpenCloud source code, at build-time from +`/services/web/assets/apps`. This cannot be manipulated at runtime. + +Additionally, the administrator can provide custom applications by storing them in the path defined by the environment +variable `WEB_ASSET_APPS_PATH`. + +This environment variable defaults to the OpenCloud base data directory `$OC_BASE_DATA_PATH/web/assets/apps`, +but can be redefined with any path set manually. + +The final list of available applications is composed of the built-in and the custom applications provided by the +administrator via `WEB_ASSET_APPS_PATH`. + +For example, if OpenCloud contains a built-in extension named `image-viewer-dfx` and the administrator provides a custom application named `image-viewer-obj` via the `WEB_ASSET_APPS_PATH` directory, the user will be able to access both +applications from the WebUI. + +### Application Structure + +* Applications always have to follow a strict structure.\ +Everything else is skipped and not considered as an application. + * Each application must be in its own directory accessed via `WEB_ASSET_APPS_PATH`. + * Each application directory must contain a `manifest.json` file. + * Each application directory can contain a `config.json` file. + +* The `manifest.json` file contains the following fields: + * `entrypoint` - required\ + The entrypoint of the application like `index.js`, the path is relative to the parent directory. + * `config` - optional\ + A list of key-value pairs that are passed to the global web application configuration `apps.yaml`. + +### Application Configuration + +If a custom configuration is needed, the administrator must provide the required configuration inside the `$OC_BASE_DATA_PATH/config/apps.yaml` file. + +NOTE: An application manifest should _never_ be changed manually, see [Using Custom Assets](#using-custom-assets) for customisation. + +The `apps.yaml` file must contain a list of key-value pairs which gets merged with the `config` field. For example, if the `image-viewer-obj` application contains the following configuration: + +```json +{ + "entrypoint": "index.js", + "config": { + "maxWidth": 1280, + "maxHeight": 1280 + } +} +``` + +The `apps.yaml` file contains the following configuration: + +```yaml +image-viewer-obj: + config: + maxHeight: 640 + maxSize: 512 +``` + +optional each application can have its own configuration file, which will be loaded by the WEB service. + +```json +{ + "config": { + "maxWidth": 320 + } +} +``` + +The Merge order is as follows: local.config overwrites > global.config overwrites > manifest.config. +The result will be: + +```json +{ + "external_apps": [ + { + "id": "image-viewer-obj", + "path": "index.js", + "config": { + "maxWidth": 320, + "maxHeight": 640, + "maxSize": 512 + } + } + ] +} +``` + +Besides the configuration from the `manifest.json` file, +the `apps.yaml` or the `config.json` file can also contain the following fields: + +* `disabled` - optional\ + Defaults to `false`. If set to `true`, the application will not be loaded. + +### Using Custom Assets + +Besides the configuration and application registration, in the process of loading the application assets, the system uses a mechanism to load custom assets. + +This is useful for cases where just a single asset should be overwritten, like a logo or similar. + +Consider the following: OpenCloud is shipped with a default web app named `image-viewer-dfx` which contains a logo, +but the administrator wants to provide a custom logo for that application. + +This can be achieved using the path defined via `WEB_ASSET_APPS_PATH` and adding a custom structure like `WEB_ASSET_APPS_PATH/image-viewer-dfx/`. Here you can add all custom assets to load like `logo.png`. On loading the web app, custom assets defined overwrite default ones. + +This also applies for the `manifest.json` file, if the administrator wants to provide a custom one. + +## Miscellaneous + +Please note that OpenCloud, in particular the web service, needs a restart to load new applications or changes to the `apps.yaml` file. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav.yaml new file mode 100644 index 00000000..1da16a7c --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav.yaml @@ -0,0 +1,40 @@ +# Autogenerated +# Filename: webdav.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9119 + token: "" + pprof: false + zpages: false +grpc_client_tls: null +http: + addr: 127.0.0.1:9115 + root: / + cors: + allow_origins: + - '*' + allow_methods: + - GET + - POST + - PUT + - PATCH + - DELETE + - OPTIONS + allow_headers: + - Authorization + - Origin + - Content-Type + - Accept + - X-Requested-With + - X-Request-Id + - Cache-Control + allow_credentials: true + tls: + enabled: false + cert: "" + key: "" +disablePreviews: false +opencloud_public_url: https://localhost:9200 +webdav_namespace: /users/{{.Id.OpaqueId}} +reva_gateway: eu.opencloud.api.gateway diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_configvars.mdx new file mode 100644 index 00000000..32877efd --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_configvars.mdx @@ -0,0 +1,22 @@ +Environment variables for the **webdav** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`WEBDAV_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`WEBDAV_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9119`| +|`WEBDAV_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`WEBDAV_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`WEBDAV_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`WEBDAV_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9115`| +|`WEBDAV_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/`| +|`OC_CORS_ALLOW_ORIGINS`
`WEBDAV_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_CORS_ALLOW_METHODS`
`WEBDAV_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`
`WEBDAV_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 Cache-Control]`| +|`OC_CORS_ALLOW_CREDENTIALS`
`WEBDAV_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_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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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_DISABLE_PREVIEWS`
`WEBDAV_DISABLE_PREVIEWS`| 1.0.0 |bool|`Set this option to 'true' to disable rendering of thumbnails triggered via webdav access. Note that when disabled, all access to preview related webdav paths will return a 404.`|`false`| +|`OC_URL`
`OC_PUBLIC_URL`| 1.0.0 |string|`URL, where OpenCloud is reachable for users.`|`https://localhost:9200`| +|`WEBDAV_WEBDAV_NAMESPACE`| 1.0.0 |string|`CS3 path layout to use when forwarding /webdav requests`|`/users/{{.Id.OpaqueId}}`| +|`OC_REVA_GATEWAY`| 1.0.0 |string|`CS3 gateway used to look up user metadata`|`eu.opencloud.api.gateway`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_readme.mdx new file mode 100755 index 00000000..b9990e0c --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webdav_readme.mdx @@ -0,0 +1,45 @@ +--- +title: Webdav +date: 2026-01-15T10:35:01.396199913Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/webdav +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The webdav service, like the [frontend](../frontend) service, provides a HTTP API following the webdav protocol. It receives HTTP calls from requestors like clients and issues gRPC calls to other services executing these requests. After the called service has finished the request, the webdav service will render their responses in `xml` and sends them back to the requestor. + + +## Table of Contents + +* [Endpoints Overview](#endpoints-overview) + * [Thumbnails](#thumbnails) + * [Search](#search) +* [Scalability](#scalability) + +## Endpoints Overview + +Currently, the webdav service handles request for two functionalities, which are `Thumbnails` and `Search`. + +### Thumbnails + +The webdav service provides various `GET` endpoints to get the thumbnails of a file in authenticated and unauthenticated contexts. It also provides thumbnails for spaces on different endpoints. + +See the [thumbnail](https://github.com/opencloud-eu/opencloud/tree/main/services/thumbnails) service for more information about thumbnails. + +### Search + +The webdav service provides access to the search functionality. It offers multiple `REPORT` endpoints for getting search results. + +See the [search](https://github.com/opencloud-eu/opencloud/tree/main/services/search) service for more details about search functionality. + +## Scalability + +The webdav service does not persist any data and does not cache any information. Therefore multiple instances of this service can be spawned in a bigger deployment like when using container orchestration with Kubernetes, without any extra configuration. + diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger.yaml b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger.yaml new file mode 100644 index 00000000..f1feab56 --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger.yaml @@ -0,0 +1,35 @@ +# Autogenerated +# Filename: webfinger.yaml + +loglevel: error +debug: + addr: 127.0.0.1:9279 + token: "" + pprof: false + zpages: false +http: + addr: 127.0.0.1:9275 + root: / + cors: + allow_origins: + - https://localhost:9200 + allow_methods: [] + allow_headers: [] + allow_credentials: false + tls: + enabled: false + cert: "" + key: "" +instances: +- claim: sub + regex: .+ + href: '{{.OC_URL}}' + titles: + en: OpenCloud Instance + break: false +relations: +- http://openid.net/specs/connect/1.0/issuer +- http://webfinger.opencloud/rel/server-instance +idp: https://localhost:9200 +opencloud_url: https://localhost:9200 +insecure: false diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_configvars.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_configvars.mdx new file mode 100644 index 00000000..d1b3fd1a --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_configvars.mdx @@ -0,0 +1,22 @@ +Environment variables for the **webfinger** service + +| Name | Introduction Version | Type | Description | Default Value | +|---|---|---|---|:---| +|`OC_LOG_LEVEL`
`WEBFINGER_LOG_LEVEL`| 1.0.0 |string|`The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.`|`error`| +|`WEBFINGER_DEBUG_ADDR`| 1.0.0 |string|`Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.`|`127.0.0.1:9279`| +|`WEBFINGER_DEBUG_TOKEN`| 1.0.0 |string|`Token to secure the metrics endpoint.`|``| +|`WEBFINGER_DEBUG_PPROF`| 1.0.0 |bool|`Enables pprof, which can be used for profiling.`|`false`| +|`WEBFINGER_DEBUG_ZPAGES`| 1.0.0 |bool|`Enables zpages, which can be used for collecting and viewing in-memory traces.`|`false`| +|`WEBFINGER_HTTP_ADDR`| 1.0.0 |string|`The bind address of the HTTP service.`|`127.0.0.1:9275`| +|`WEBFINGER_HTTP_ROOT`| 1.0.0 |string|`Subdirectory that serves as the root for this HTTP service.`|`/`| +|`OC_CORS_ALLOW_ORIGINS`
`WEBFINGER_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.`|`[https://localhost:9200]`| +|`OC_CORS_ALLOW_METHODS`
`WEBFINGER_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.`|`[]`| +|`OC_CORS_ALLOW_HEADERS`
`WEBFINGER_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.`|`[]`| +|`OC_CORS_ALLOW_CREDENTIALS`
`WEBFINGER_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.`|`false`| +|`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_CERTIFICATE`| 1.0.0 |string|`Path/File name of the TLS server certificate (in PEM format) for the http services.`|``| +|`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.`|``| +|`WEBFINGER_RELATIONS`| 1.0.0 |[]string|`A list of relation URIs or registered relation types to add to webfinger responses. See the Environment Variable Types description for more details.`|`[http://openid.net/specs/connect/1.0/issuer http://webfinger.opencloud/rel/server-instance]`| +|`OC_URL`
`OC_OIDC_ISSUER`
`WEBFINGER_OIDC_ISSUER`| 1.0.0 |string|`The identity provider href for the openid-discovery relation.`|`https://localhost:9200`| +|`OC_URL`
`WEBFINGER_OPENCLOUD_SERVER_INSTANCE_URL`| 1.0.0 |string|`The URL for the legacy OpenCloud server instance relation (not to be confused with the product OpenCloud Server). It defaults to the OC_URL but can be overridden to support some reverse proxy corner cases. To shard the deployment, multiple instances can be configured in the configuration file.`|`https://localhost:9200`| +|`OC_INSECURE`
`WEBFINGER_INSECURE`| 1.0.0 |bool|`Allow insecure connections to the WEBFINGER service.`|`false`| diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_deprecation.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_deprecation.mdx new file mode 100644 index 00000000..e69de29b diff --git a/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_readme.mdx b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_readme.mdx new file mode 100755 index 00000000..d45bdcfc --- /dev/null +++ b/versioned_docs/version-stablecitest-12.3.4/dev/_static/env-vars/webfinger_readme.mdx @@ -0,0 +1,144 @@ +--- +title: Webfinger +date: 2026-01-15T10:35:01.396314463Z +weight: 20 +geekdocRepo: https://github.com/opencloud-eu/opencloud +geekdocEditPath: edit/master/services/webfinger +geekdocFilePath: README.md +geekdocCollapseSection: true +--- + + + +## Abstract + + +The webfinger service provides an RFC7033 WebFinger lookup of OpenCloud instances relevant for a given user account via endpoints a the /.well-known/webfinger implementation. + + +## Table of Contents + +* [OpenID Connect Discovery](#openid-connect-discovery) +* [Authenticated Instance Discovery](#authenticated-instance-discovery) +* [Configure Different Instances Based on OpenidConnect UserInfo Claims](#configure-different-instances-based-on-openidconnect-userinfo-claims) + +## OpenID Connect Discovery + +Clients can make an unauthenticated `GET https://drive.opencloud.test/.well-known/webfinger?resource=https%3A%2F%2Fdrive.opencloud.test` request to discover the OpenID Connect Issuer in the `http://openid.net/specs/connect/1.0/issuer` relation: + +```json +{ + "subject": "https://drive.opencloud.test", + "links": [ + { + "rel": "http://openid.net/specs/connect/1.0/issuer", + "href": "https://sso.example.org/cas/oidc/" + } + ] +} +``` + +Here, the `resource` takes the instance domain URI, but an `acct:` URI works as well. + +## Authenticated Instance Discovery + +When using OpenID connect to authenticate requests, clients can look up the opencloud instances a user has access to. + +* Authentication is necessary to prevent leaking information about existing users. +* Basic auth is not supported. + +The default configuration will simply return the `OC_URL` and direct clients to that domain: + +```json +{ + "subject": "acct:alan@drive.opencloud.test", + "links": [ + { + "rel": "http://openid.net/specs/connect/1.0/issuer", + "href": "https://sso.example.org/cas/oidc/" + }, + { + "rel": "http://webfinger.opencloud/rel/server-instance", + "href": "https://abc.drive.example.org", + "titles": { + "en": "OpenCloud Instance" + } + } + ] +} +``` + +## Configure Different Instances Based on OpenidConnect UserInfo Claims + +A more complex example for configuring different instances could look like this: + +```yaml +webfinger: + instances: + - claim: email + regex: alan@example\.org + href: "https://{{.preferred_username}}.cloud.opencloud.test" + title: + "en": "OpenCloud Instance for Alan" + "de": "OpenCloud Instanz für Alan" + break: true + - claim: "email" + regex: mary@example\.org + href: "https://{{.preferred_username}}.cloud.opencloud.test" + title: + "en": "OpenCloud Instance for Mary" + "de": "OpenCloud Instanz für Mary" + break: false + - claim: "email" + regex: .+@example\.org + href: "https://example-org.cloud.opencloud.test" + title: + "en": "OpenCloud Instance for example.org" + "de": "OpenCloud Instanz für example.org" + break: true + - claim: "email" + regex: .+@example\.com + href: "https://example-com.cloud.opencloud.test" + title: + "en": "OpenCloud Instance for example.com" + "de": "OpenCloud Instanz für example.com" + break: true + - claim: "email" + regex: .+@.+\..+ + href: "https://cloud.opencloud.test" + title: + "en": "OpenCloud Instance" + "de": "OpenCloud Instanz" + break: true +``` + +Now, an authenticated webfinger request for `acct:me@example.org` (when logged in as mary) would return two instances, based on her `email` claim, the regex matches and break flags: + +```json +{ + "subject": "acct:mary@example.org", + "links": [ + { + "rel": "http://openid.net/specs/connect/1.0/issuer", + "href": "https://sso.example.org/cas/oidc/" + }, + { + "rel": "http://webfinger.opencloud/rel/server-instance", + "href": "https://mary.cloud.opencloud.test", + "titles": { + "en": "OpenCloud Instance for Mary", + "de": "OpenCloud Instanz für Mary" + } + }, + { + "rel": "http://webfinger.opencloud/rel/server-instance", + "href": "https://xyz.drive.example.org", + "titles": { + "en": "OpenCloud Instance for example.org", + "de": "OpenCloud Instanz für example.org" + } + } + ] +} +``` +