Merge pull request #3968 from wkloucek/add-more-config-desc

add more configuration descriptions

extensions/app-provider/pkg/config/config.go

@@ -18,8 +18,8 @@ type Config struct {
 	TokenManager *TokenManager `yaml:"token_manager"`
 	Reva         *Reva         `yaml:"reva"`
 
-	ExternalAddr string  `yaml:"external_addr" env:"APP_PROVIDER_EXTERNAL_ADDR" desc:"Address of the app provider, where the gateway service can reach it"`
+	ExternalAddr string  `yaml:"external_addr" env:"APP_PROVIDER_EXTERNAL_ADDR" desc:"Address of the app provider, where the gateway service can reach it."`
-	Driver       string  `yaml:"driver" env:"APP_PROVIDER_DRIVER" desc:"Driver, which the app provider uses"`
+	Driver       string  `yaml:"driver" env:"APP_PROVIDER_DRIVER" desc:"Driver, which the app provider uses. Only \"wopi\" is supported as of now."`
 	Drivers      Drivers `yaml:"drivers"`
 
 	Supervised bool            `yaml:"-"`
@@ -62,13 +62,13 @@ type Drivers struct {
 }
 
 type WOPIDriver struct {
-	AppAPIKey      string `yaml:"app_api_key" env:"APP_PROVIDER_WOPI_APP_API_KEY" desc:"api key for the wopi app"`
+	AppAPIKey      string `yaml:"app_api_key" env:"APP_PROVIDER_WOPI_APP_API_KEY" desc:"API key for the wopi app."`
-	AppDesktopOnly bool   `yaml:"app_desktop_only" env:"APP_PROVIDER_WOPI_APP_DESKTOP_ONLY" desc:"offer this app only on desktop"`
+	AppDesktopOnly bool   `yaml:"app_desktop_only" env:"APP_PROVIDER_WOPI_APP_DESKTOP_ONLY" desc:"Offer this app only on desktop."`
-	AppIconURI     string `yaml:"app_icon_uri" env:"APP_PROVIDER_WOPI_APP_ICON_URI" desc:"uri to an app icon to be used by clients"`
+	AppIconURI     string `yaml:"app_icon_uri" env:"APP_PROVIDER_WOPI_APP_ICON_URI" desc:"URI to an app icon to be used by clients."`
-	AppInternalURL string `yaml:"app_internal_url" env:"APP_PROVIDER_WOPI_APP_INTERNAL_URL" desc:"internal url to the app, eg in your DMZ"`
+	AppInternalURL string `yaml:"app_internal_url" env:"APP_PROVIDER_WOPI_APP_INTERNAL_URL" desc:"Internal URL to the app, eg in your DMZ."`
-	AppName        string `yaml:"app_name" env:"APP_PROVIDER_WOPI_APP_NAME" desc:"human readable app name"`
+	AppName        string `yaml:"app_name" env:"APP_PROVIDER_WOPI_APP_NAME" desc:"Human readable app name."`
-	AppURL         string `yaml:"app_url" env:"APP_PROVIDER_WOPI_APP_URL" desc:"url for end users to access the app"`
+	AppURL         string `yaml:"app_url" env:"APP_PROVIDER_WOPI_APP_URL" desc:"URL for end users to access the app."`
-	Insecure       bool   `yaml:"insecure" env:"APP_PROVIDER_WOPI_INSECURE" desc:"allow insecure connections to the app"`
+	Insecure       bool   `yaml:"insecure" env:"APP_PROVIDER_WOPI_INSECURE" desc:"Allow insecure connections to the app."`
-	IopSecret      string `yaml:"wopi_server_iop_secret" env:"APP_PROVIDER_WOPI_WOPI_SERVER_IOP_SECRET" desc:"shared secret of the CS3org WOPI server"`
+	IopSecret      string `yaml:"wopi_server_iop_secret" env:"APP_PROVIDER_WOPI_WOPI_SERVER_IOP_SECRET" desc:"Shared secret of the CS3org WOPI server."`
-	WopiURL        string `yaml:"wopi_server_external_url" env:"APP_PROVIDER_WOPI_WOPI_SERVER_EXTERNAL_URL" desc:"external url of the CS3org WOPI server"`
+	WopiURL        string `yaml:"wopi_server_external_url" env:"APP_PROVIDER_WOPI_WOPI_SERVER_EXTERNAL_URL" desc:"External url of the CS3org WOPI server."`
 }

extensions/app-provider/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/app-registry/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/auth-basic/pkg/config/config.go

@@ -80,7 +80,7 @@ type LDAPProvider struct {
 	GroupFilter      string          `yaml:"group_filter" env:"LDAP_GROUP_FILTER;AUTH_BASIC_LDAP_GROUP_FILTER" desc:"LDAP filter to add to the default filters for group searches."`
 	UserObjectClass  string          `yaml:"user_object_class" env:"LDAP_USER_OBJECTCLASS;AUTH_BASIC_LDAP_USER_OBJECTCLASS" desc:"The object class to use for users in the default user search filter ('inetOrgPerson')."`
 	GroupObjectClass string          `yaml:"group_object_class" env:"LDAP_GROUP_OBJECTCLASS;AUTH_BASIC_LDAP_GROUP_OBJECTCLASS" desc:"The object class to use for groups in the default group search filter ('groupOfNames'). "`
-	LoginAttributes  []string        `yaml:"login_attributes" env:"LDAP_LOGIN_ATTRIBUTES;AUTH_BASIC_LDAP_LOGIN_ATTRIBUTES"`
+	LoginAttributes  []string        `yaml:"login_attributes" env:"LDAP_LOGIN_ATTRIBUTES;AUTH_BASIC_LDAP_LOGIN_ATTRIBUTES" desc:"The user object attributes, that can be used for login."`
 	IDP              string          `yaml:"idp" env:"OCIS_URL;OCIS_OIDC_ISSUER;AUTH_BASIC_IDP_URL" desc:"The identity provider value to set in the userids of the CS3 user objects for users returned by this user provider."`
 	UserSchema       LDAPUserSchema  `yaml:"user_schema"`
 	GroupSchema      LDAPGroupSchema `yaml:"group_schema"`
@@ -110,7 +110,7 @@ type OwnCloudSQLProvider struct {
 	DBPort           int    `yaml:"db_port" env:"AUTH_BASIC_OWNCLOUDSQL_DB_PORT" desc:"Network port to use for the database connection."`
 	DBName           string `yaml:"db_name" env:"AUTH_BASIC_OWNCLOUDSQL_DB_NAME" desc:"Name of the owncloud database."`
 	IDP              string `yaml:"idp" env:"AUTH_BASIC_OWNCLOUDSQL_IDP" desc:"The identity provider value to set in the userids of the CS3 user objects for users returned by this user provider."`
-	Nobody           int64  `yaml:"nobody" env:"AUTH_BASIC_OWNCLOUDSQL_NOBODY"` // TODO what is this?
+	Nobody           int64  `yaml:"nobody" env:"AUTH_BASIC_OWNCLOUDSQL_NOBODY" desc:"Fallback number if no numeric UID and GID properties are provided."`
 	JoinUsername     bool   `yaml:"join_username" env:"AUTH_BASIC_OWNCLOUDSQL_JOIN_USERNAME" desc:"Join the user properties table to read usernames"`
 	JoinOwnCloudUUID bool   `yaml:"join_owncloud_uuid" env:"AUTH_BASIC_OWNCLOUDSQL_JOIN_OWNCLOUD_UUID" desc:"Join the user properties table to read user ids (boolean)."`
 }

extensions/auth-basic/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/auth-bearer/pkg/config/config.go

@@ -18,7 +18,7 @@ type Config struct {
 	TokenManager *TokenManager `yaml:"token_manager"`
 	Reva         *Reva         `yaml:"reva"`
 
-	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_BEARER_SKIP_USER_GROUPS_IN_TOKEN"`
+	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_BEARER_SKIP_USER_GROUPS_IN_TOKEN" desc:"Skip storing all groups of a user in the jwt token."`
 
 	OIDC OIDC `yaml:"oidc"`
 
@@ -57,9 +57,9 @@ type GRPCConfig struct {
 }
 
 type OIDC struct {
-	Issuer   string `yaml:"issuer" env:"OCIS_URL;OCIS_OIDC_ISSUER;AUTH_BEARER_OIDC_ISSUER"`
+	Issuer   string `yaml:"issuer" env:"OCIS_URL;OCIS_OIDC_ISSUER;AUTH_BEARER_OIDC_ISSUER" desc:"URL of the OIDC issuer. It defaults to URL of the builtin IDP."`
-	Insecure bool   `yaml:"insecure" env:"OCIS_INSECURE;AUTH_BEARER_OIDC_INSECURE"`
+	Insecure bool   `yaml:"insecure" env:"OCIS_INSECURE;AUTH_BEARER_OIDC_INSECURE" desc:"Allow insecure connections to the OIDC issuer."`
-	IDClaim  string `yaml:"id_claim" env:"AUTH_BEARER_OIDC_ID_CLAIM"`
+	IDClaim  string `yaml:"id_claim" env:"AUTH_BEARER_OIDC_ID_CLAIM" desc:"Name of the claim, which holds the user identifier."`
-	UIDClaim string `yaml:"uid_claim" env:"AUTH_BEARER_OIDC_UID_CLAIM"`
+	UIDClaim string `yaml:"uid_claim" env:"AUTH_BEARER_OIDC_UID_CLAIM" desc:"Name of the claim, which holds the UID."`
-	GIDClaim string `yaml:"gid_claim" env:"AUTH_BEARER_OIDC_GID_CLAIM"`
+	GIDClaim string `yaml:"gid_claim" env:"AUTH_BEARER_OIDC_GID_CLAIM" desc:"Name of the claim, which holds the GID."`
 }

extensions/auth-bearer/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/auth-machine/pkg/config/config.go

@@ -18,9 +18,9 @@ type Config struct {
 	TokenManager *TokenManager `yaml:"token_manager"`
 	Reva         *Reva         `yaml:"reva"`
 
-	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_MACHINE_SKIP_USER_GROUPS_IN_TOKEN"`
+	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"AUTH_MACHINE_SKIP_USER_GROUPS_IN_TOKEN" desc:"Skip storing all groups of a user in the jwt token."`
 
-	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;AUTH_MACHINE_API_KEY"`
+	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;AUTH_MACHINE_API_KEY" desc:"Machine auth API key used for validating requests from other services when impersonating users."`
 
 	Supervised bool            `yaml:"-"`
 	Context    context.Context `yaml:"-"`

extensions/auth-machine/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/frontend/pkg/config/config.go

@@ -21,7 +21,7 @@ type Config struct {
 
 	TokenManager      *TokenManager `yaml:"token_manager"`
 	Reva              *Reva         `yaml:"reva"`
-	MachineAuthAPIKey string        `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;FRONTEND_MACHINE_AUTH_API_KEY"`
+	MachineAuthAPIKey string        `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;FRONTEND_MACHINE_AUTH_API_KEY"  desc: "Machine auth API key used for accessing the 'auth-machine' service to impersonate users."`
 
 	SkipUserGroupsInToken bool `yaml:"skip_user_groups_in_token" env:"FRONTEND_SKIP_USER_GROUPS_IN_TOKEN"`
 

extensions/frontend/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/gateway/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/graph-explorer/pkg/config/config.go

@@ -25,8 +25,8 @@ type Config struct {
 
 // GraphExplorer defines the available graph-explorer configuration.
 type GraphExplorer struct {
-	ClientID     string `yaml:"client_id" env:"GRAPH_EXPLORER_CLIENT_ID"`
+	ClientID     string `yaml:"client_id" env:"GRAPH_EXPLORER_CLIENT_ID" desc:"OIDC client id, the graph explorer uses. This client needs to be set up in your IDP."`
-	Issuer       string `yaml:"issuer" env:"OCIS_URL;OCIS_OIDC_ISSUER;GRAPH_EXPLORER_ISSUER"`
+	Issuer       string `yaml:"issuer" env:"OCIS_URL;OCIS_OIDC_ISSUER;GRAPH_EXPLORER_ISSUER" desc:"URL of the OIDC issuer. It defaults to URL of the builtin IDP."`
-	GraphURLBase string `yaml:"graph_url_base" env:"OCIS_URL;GRAPH_EXPLORER_GRAPH_URL_BASE"`
+	GraphURLBase string `yaml:"graph_url_base" env:"OCIS_URL;GRAPH_EXPLORER_GRAPH_URL_BASE" desc:"Base URL, where the graph explorer is reachable for users."`
-	GraphURLPath string `yaml:"graph_url_path" env:"GRAPH_EXPLORER_GRAPH_URL_PATH"`
+	GraphURLPath string `yaml:"graph_url_path" env:"GRAPH_EXPLORER_GRAPH_URL_PATH" desc:"URL path, where the graph explorer is reachable for users."`
 }

extensions/graph/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/groups/pkg/config/config.go

@@ -107,7 +107,7 @@ type OwnCloudSQLDriver struct {
 	DBPort             int    `yaml:"db_port" env:"GROUPS_OWNCLOUDSQL_DB_PORT" desc:"Network port to use for the database connection."`
 	DBName             string `yaml:"db_name" env:"GROUPS_OWNCLOUDSQL_DB_NAME" desc:"Name of the owncloud database."`
 	IDP                string `yaml:"idp" env:"GROUPS_OWNCLOUDSQL_IDP" desc:"The identity provider value to set in the userids of the CS3 user objects for users returned by this user provider."`
-	Nobody             int64  `yaml:"nobody" env:"GROUPS_OWNCLOUDSQL_NOBODY"` // TODO what is this?
+	Nobody             int64  `yaml:"nobody" env:"GROUPS_OWNCLOUDSQL_NOBODY" desc:"Fallback number if no numeric UID and GID properties are provided."`
 	JoinUsername       bool   `yaml:"join_username" env:"GROUPS_OWNCLOUDSQL_JOIN_USERNAME" desc:"Join the user properties table to read usernames (boolean)"`
 	JoinOwnCloudUUID   bool   `yaml:"join_owncloud_uuid" env:"GROUPS_OWNCLOUDSQL_JOIN_OWNCLOUD_UUID" desc:"Join the user properties table to read user ids (boolean)."`
 	EnableMedialSearch bool   `yaml:"enable_medial_search" env:"GROUPS_OWNCLOUDSQL_ENABLE_MEDIAL_SEARCH" desc:"Allow 'medial search' when searching for users instead of just doing a prefix search. (Allows finding 'Alice' when searching for 'lic'.)"`

extensions/groups/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/idm/pkg/config/config.go

@@ -20,7 +20,7 @@ type Config struct {
 	CreateDemoUsers bool     `yaml:"create_demo_users" env:"IDM_CREATE_DEMO_USERS;ACCOUNTS_DEMO_USERS_AND_GROUPS" desc:"Flag to enabe/disable the creation of the demo users"`
 
 	ServiceUserPasswords ServiceUserPasswords `yaml:"service_user_passwords"`
-	AdminUserID          string               `yaml:"admin_user_id" env:"OCIS_ADMIN_USER_ID;IDM_ADMIN_USER_ID"`
+	AdminUserID          string               `yaml:"admin_user_id" env:"OCIS_ADMIN_USER_ID;IDM_ADMIN_USER_ID" desc:"ID of a user, that should receive admin privileges."`
 
 	Context context.Context `yaml:"-"`
 }

extensions/idp/pkg/config/config.go

@@ -18,8 +18,9 @@ type Config struct {
 
 	HTTP HTTP `yaml:"http"`
 
-	Reva              *Reva  `yaml:"reva"`
+	Reva *Reva `yaml:"reva"`
-	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;IDP_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used to impersonate users when looking up their userinfo via the 'cs3' backend."`
+
+	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;IDP_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used for accessing the 'auth-machine' service to impersonate users when looking up their userinfo via the 'cs3' backend."`
 
 	Asset   Asset    `yaml:"asset"`
 	IDP     Settings `yaml:"idp"`

extensions/nats/pkg/config/config.go

@@ -22,8 +22,8 @@ type Config struct {
 
 // Nats is the nats config
 type Nats struct {
-	Host      string `yaml:"host" env:"NATS_NATS_HOST"`
+	Host      string `yaml:"host" env:"NATS_NATS_HOST" desc:"Bind address."`
-	Port      int    `yaml:"port" env:"NATS_NATS_PORT"`
+	Port      int    `yaml:"port" env:"NATS_NATS_PORT" desc:"Bind port:"`
-	ClusterID string `yaml:"clusterid" env:"NATS_NATS_CLUSTER_ID"`
+	ClusterID string `yaml:"clusterid" env:"NATS_NATS_CLUSTER_ID" desc:"ID of the NATS cluster."`
-	StoreDir  string `yaml:"store_dir" env:"NATS_NATS_STORE_DIR"`
+	StoreDir  string `yaml:"store_dir" env:"NATS_NATS_STORE_DIR" desc:"Path for the NATS JetStream persistence directory."`
 }

extensions/notifications/pkg/config/config.go

@@ -25,20 +25,20 @@ type Notifications struct {
 	SMTP              SMTP   `yaml:"SMTP"`
 	Events            Events `yaml:"events"`
 	RevaGateway       string `yaml:"reva_gateway" env:"REVA_GATEWAY;NOTIFICATIONS_REVA_GATEWAY" desc:"CS3 gateway used to look up user metadata"`
-	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;NOTIFICATIONS_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used to impersonate users when looking up their email"`
+	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;NOTIFICATIONS_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used for accessing the 'auth-machine' service to look up their email."`
 }
 
 // SMTP combines the smtp configuration options.
 type SMTP struct {
-	Host     string `yaml:"smtp_host" env:"NOTIFICATIONS_SMTP_HOST"`
+	Host     string `yaml:"smtp_host" env:"NOTIFICATIONS_SMTP_HOST" desc:"SMTP host, to connect to."`
-	Port     string `yaml:"smtp_port" env:"NOTIFICATIONS_SMTP_PORT"`
+	Port     string `yaml:"smtp_port" env:"NOTIFICATIONS_SMTP_PORT" desc:"Port of the SMTP host, to connect to."`
-	Sender   string `yaml:"smtp_sender" env:"NOTIFICATIONS_SMTP_SENDER"`
+	Sender   string `yaml:"smtp_sender" env:"NOTIFICATIONS_SMTP_SENDER" desc:"Sender of emails, that will be sent."`
-	Password string `yaml:"smtp_password" env:"NOTIFICATIONS_SMTP_PASSWORD"`
+	Password string `yaml:"smtp_password" env:"NOTIFICATIONS_SMTP_PASSWORD" desc:"Password of the SMTP host, to connect to."`
 }
 
 // Events combines the configuration options for the event bus.
 type Events struct {
-	Endpoint      string `yaml:"endpoint" env:"NOTIFICATIONS_EVENTS_ENDPOINT"`
+	Endpoint      string `yaml:"endpoint" env:"NOTIFICATIONS_EVENTS_ENDPOINT" desc:"Endpoint of the event system."`
-	Cluster       string `yaml:"cluster" env:"NOTIFICATIONS_EVENTS_CLUSTER"`
+	Cluster       string `yaml:"cluster" env:"NOTIFICATIONS_EVENTS_CLUSTER" desc:"Cluster ID of the event system."`
-	ConsumerGroup string `yaml:"group" env:"NOTIFICATIONS_EVENTS_GROUP"`
+	ConsumerGroup string `yaml:"group" env:"NOTIFICATIONS_EVENTS_GROUP" desc:"Name of the event group / queue on the event system."`
 }

extensions/ocdav/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/ocs/pkg/config/config.go

@@ -24,7 +24,7 @@ type Config struct {
 	IdentityManagement IdentityManagement `yaml:"identity_management"`
 
 	AccountBackend    string `yaml:"account_backend" env:"OCS_ACCOUNT_BACKEND_TYPE"`
-	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;OCS_MACHINE_AUTH_API_KEY"`
+	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;OCS_MACHINE_AUTH_API_KEY" desc: "Machine auth API key used for accessing the 'auth-machine' service to impersonate users."`
 
 	Context context.Context `yaml:"-"`
 }
@@ -33,5 +33,5 @@ type Config struct {
 // is based in the combination of IDP hostname + UserID. For more information see:
 // https://github.com/cs3org/reva/blob/4fd0229f13fae5bc9684556a82dbbd0eced65ef9/pkg/storage/utils/decomposedfs/node/node.go#L856-L865
 type IdentityManagement struct {
-	Address string `yaml:"address" env:"OCIS_URL;OCIS_OIDC_ISSUER;OCS_IDM_ADDRESS"`
+	Address string `yaml:"address" env:"OCIS_URL;OCIS_OIDC_ISSUER;OCS_IDM_ADDRESS" desc:"URL of the OIDC issuer. It defaults to URL of the builtin IDP."`
 }

extensions/ocs/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/proxy/pkg/config/config.go

@@ -28,7 +28,7 @@ type Config struct {
 	AccountBackend        string          `yaml:"account_backend" env:"PROXY_ACCOUNT_BACKEND_TYPE" desc:"Account backend the proxy should use, currenly only 'cs3' is possible here."`
 	UserOIDCClaim         string          `yaml:"user_oidc_claim" env:"PROXY_USER_OIDC_CLAIM" desc:"The name of an OpenID Connect claim that should be used for resolving users with the account backend. Currently defaults to 'email'."`
 	UserCS3Claim          string          `yaml:"user_cs3_claim" env:"PROXY_USER_CS3_CLAIM" desc:"The name of a CS3 user attribute (claim) that should be mapped to the 'user_oidc_claim'. Currently defaults to 'mail' (other possible values are: 'username', 'displayname')"`
-	MachineAuthAPIKey     string          `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;PROXY_MACHINE_AUTH_API_KEY" desc: "Machine auth API key used for accessing the 'auth-machine' service."`
+	MachineAuthAPIKey     string          `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;PROXY_MACHINE_AUTH_API_KEY" desc: "Machine auth API key used for accessing the 'auth-machine' service to impersonate users."`
 	AutoprovisionAccounts bool            `yaml:"auto_provision_accounts" env:"PROXY_AUTOPROVISION_ACCOUNTS" desc:"Set this to 'true' to automatically provsion users that do not yet exist in the users service on-demand upon first signin. To use this a write-enabled libregraph user backend needs to be setup an running."`
 	EnableBasicAuth       bool            `yaml:"enable_basic_auth" env:"PROXY_ENABLE_BASIC_AUTH" desc:"Set this to true to enable 'basic' (username/password) authentication. (Default: false)"`
 	InsecureBackends      bool            `yaml:"insecure_backends" env:"PROXY_INSECURE_BACKENDS" desc:"Disable TLS certificate validation for all http backend connections. (Default: false)"`
@@ -83,7 +83,7 @@ type AuthMiddleware struct {
 // OIDC is the config for the OpenID-Connect middleware. If set the proxy will try to authenticate every request
 // with the configured oidc-provider
 type OIDC struct {
-	Issuer        string        `yaml:"issuer" env:"OCIS_URL;OCIS_OIDC_ISSUER;PROXY_OIDC_ISSUER" desc:"URL of the OpenID connect identity provider."`
+	Issuer        string        `yaml:"issuer" env:"OCIS_URL;OCIS_OIDC_ISSUER;PROXY_OIDC_ISSUER" desc:"URL of the OIDC issuer. It defaults to URL of the builtin IDP."`
 	Insecure      bool          `yaml:"insecure" env:"OCIS_INSECURE;PROXY_OIDC_INSECURE" desc:"Disable TLS certificate validation for connections to the IDP. (not recommended for production environments."`
 	UserinfoCache UserinfoCache `yaml:"user_info_cache"`
 }

extensions/proxy/pkg/config/reva.go

@@ -2,5 +2,5 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }

extensions/search/pkg/config/config.go

@@ -22,7 +22,7 @@ type Config struct {
 	Reva     Reva   `yaml:"reva"`
 	Events   Events `yaml:"events"`
 
-	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;SEARCH_MACHINE_AUTH_API_KEY"`
+	MachineAuthAPIKey string `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;SEARCH_MACHINE_AUTH_API_KEY" desc: "Machine auth API key used for accessing the 'auth-machine' service to impersonate users."`
 
 	Context context.Context `yaml:"-"`
 }

extensions/search/pkg/config/reva.go

@@ -2,5 +2,5 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `ocisConfig:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `ocisConfig:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }

extensions/settings/pkg/config/config.go

@@ -23,7 +23,7 @@ type Config struct {
 	DataPath  string   `yaml:"data_path" env:"SETTINGS_DATA_PATH"`
 	Metadata  Metadata `yaml:"metadata_config"`
 
-	AdminUserID string `yaml:"admin_user_id" env:"OCIS_ADMIN_USER_ID;SETTINGS_ADMIN_USER_ID"`
+	AdminUserID string `yaml:"admin_user_id" env:"OCIS_ADMIN_USER_ID;SETTINGS_ADMIN_USER_ID" desc:"ID of a user, that should receive admin privileges."`
 
 	Asset        Asset         `yaml:"asset"`
 	TokenManager *TokenManager `yaml:"token_manager"`

extensions/sharing/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/storage-publiclink/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/storage-shares/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/storage-system/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/storage-users/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/thumbnails/pkg/config/config.go

@@ -35,7 +35,7 @@ type Thumbnail struct {
 	FileSystemStorage   FileSystemStorage `yaml:"filesystem_storage"`
 	WebdavAllowInsecure bool              `yaml:"webdav_allow_insecure" env:"OCIS_INSECURE;THUMBNAILS_WEBDAVSOURCE_INSECURE" desc:"Ignore untrusted SSL certificates when connecting to the webdav source."`
 	CS3AllowInsecure    bool              `yaml:"cs3_allow_insecure" env:"OCIS_INSECURE;THUMBNAILS_CS3SOURCE_INSECURE" desc:"Ignore untrusted SSL certificates when connecting to the CS3 source."`
-	RevaGateway         string            `yaml:"reva_gateway" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"` //TODO: use REVA config
+	RevaGateway         string            `yaml:"reva_gateway" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."` //TODO: use REVA config
 	FontMapFile         string            `yaml:"font_map_file" env:"THUMBNAILS_TXT_FONTMAP_FILE" desc:"The path to a font file for txt thumbnails."`
 	TransferSecret      string            `yaml:"transfer_secret" env:"THUMBNAILS_TRANSFER_TOKEN" desc:"The secret to sign JWT to download the actual thumbnail file."`
 	DataEndpoint        string            `yaml:"data_endpoint" env:"THUMBNAILS_DATA_ENDPOINT" desc:"The HTTP endpoint where the actual thumbnail file can be downloaded."`

extensions/users/pkg/config/config.go

@@ -111,7 +111,7 @@ type OwnCloudSQLDriver struct {
 	DBPort             int    `yaml:"db_port" env:"USERS_OWNCLOUDSQL_DB_PORT" desc:"Network port to use for the database connection."`
 	DBName             string `yaml:"db_name" env:"USERS_OWNCLOUDSQL_DB_NAME" desc:"Name of the owncloud database."`
 	IDP                string `yaml:"idp" env:"USERS_OWNCLOUDSQL_IDP" desc:"The identity provider value to set in the userids of the CS3 user objects for users returned by this user provider."`
-	Nobody             int64  `yaml:"nobody" env:"USERS_OWNCLOUDSQL_NOBODY"` // TODO what is this?
+	Nobody             int64  `yaml:"nobody" env:"USERS_OWNCLOUDSQL_NOBODY" desc:"Fallback number if no numeric UID and GID properties are provided."`
 	JoinUsername       bool   `yaml:"join_username" env:"USERS_OWNCLOUDSQL_JOIN_USERNAME" desc:"Join the user properties table to read usernames"`
 	JoinOwnCloudUUID   bool   `yaml:"join_owncloud_uuid" env:"USERS_OWNCLOUDSQL_JOIN_OWNCLOUD_UUID" desc:"Join the user properties table to read user ids (boolean)."`
 	EnableMedialSearch bool   `yaml:"enable_medial_search" env:"USERS_OWNCLOUDSQL_ENABLE_MEDIAL_SEARCH" desc:"Allow 'medial search' when searching for users instead of just doing a prefix search. (Allows finding 'Alice' when searching for 'lic'.)"`

extensions/users/pkg/config/reva.go

@@ -2,7 +2,7 @@ package config
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // TokenManager is the config for using the reva token manager

extensions/web/pkg/config/config.go

@@ -44,7 +44,7 @@ type WebConfig struct {
 // OIDC defines the available oidc configuration
 type OIDC struct {
 	MetadataURL  string `json:"metadata_url,omitempty" yaml:"metadata_url" env:"WEB_OIDC_METADATA_URL"`
-	Authority    string `json:"authority,omitempty" yaml:"authority" env:"OCIS_URL;OCIS_OIDC_ISSUER;WEB_OIDC_AUTHORITY"`
+	Authority    string `json:"authority,omitempty" yaml:"authority" env:"OCIS_URL;OCIS_OIDC_ISSUER;WEB_OIDC_AUTHORITY" desc:"URL of the OIDC issuer. It defaults to URL of the builtin IDP."`
 	ClientID     string `json:"client_id,omitempty" yaml:"client_id" env:"WEB_OIDC_CLIENT_ID"`
 	ResponseType string `json:"response_type,omitempty" yaml:"response_type" env:"WEB_OIDC_RESPONSE_TYPE"`
 	Scope        string `json:"scope,omitempty" yaml:"scope" env:"WEB_OIDC_SCOPE"`

extensions/webdav/pkg/config/config.go

@@ -19,8 +19,8 @@ type Config struct {
 	HTTP HTTP `yaml:"http"`
 
 	OcisPublicURL   string `yaml:"ocis_public_url" env:"OCIS_URL;OCIS_PUBLIC_URL"`
-	WebdavNamespace string `yaml:"webdav_namespace" env:"WEBDAV_WEBDAV_NAMESPACE" desc:"CS3 path layout to use when forwarding /webdav requests"` //TODO: prevent this cross config
+	WebdavNamespace string `yaml:"webdav_namespace" env:"WEBDAV_WEBDAV_NAMESPACE" desc:"CS3 path layout to use when forwarding /webdav requests"`
-	RevaGateway     string `yaml:"reva_gateway" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	RevaGateway     string `yaml:"reva_gateway" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 
 	Context context.Context `yaml:"-"`
 }

ocis-pkg/config/config.go

@@ -65,11 +65,11 @@ type Config struct {
 
 	Registry          string               `yaml:"registry"`
 	TokenManager      *shared.TokenManager `yaml:"token_manager"`
-	MachineAuthAPIKey string               `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY"`
+	MachineAuthAPIKey string               `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used for accessing the 'auth-machine' service to impersonate users."`
 	TransferSecret    string               `yaml:"transfer_secret" env:"STORAGE_TRANSFER_SECRET"`
 	SystemUserID      string               `yaml:"system_user_id" env:"OCIS_SYSTEM_USER_ID"`
 	SystemUserAPIKey  string               `yaml:"system_user_api_key" env:"OCIS_SYSTEM_USER_API_KEY"`
-	AdminUserID       string               `yaml:"admin_user_id" env:"OCIS_ADMIN_USER_ID"`
+	AdminUserID       string               `yaml:"admin_user_id" env:"OCIS_ADMIN_USER_ID" desc:"ID of a user, that should receive admin privileges."`
 	Runtime           Runtime              `yaml:"runtime"`
 
 	AppProvider       *appProvider.Config   `yaml:"app_provider"`

ocis-pkg/shared/shared_types.go

@@ -31,7 +31,7 @@ type TokenManager struct {
 
 // Reva defines all available REVA configuration.
 type Reva struct {
-	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint"`
+	Address string `yaml:"address" env:"REVA_GATEWAY" desc:"The CS3 gateway endpoint."`
 }
 
 // Commons holds configuration that are common to all extensions. Each extension can then decide whether
@@ -42,9 +42,9 @@ type Commons struct {
 	OcisURL           string        `yaml:"ocis_url" env:"OCIS_URL"`
 	TokenManager      *TokenManager `yaml:"token_manager"`
 	Reva              *Reva         `yaml:"reva"`
-	MachineAuthAPIKey string        `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY"`
+	MachineAuthAPIKey string        `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used for accessing the 'auth-machine' service to impersonate users."`
 	TransferSecret    string        `yaml:"transfer_secret,omitempty" env:"REVA_TRANSFER_SECRET"`
 	SystemUserID      string        `yaml:"system_user_id" env:"OCIS_SYSTEM_USER_ID"`
 	SystemUserAPIKey  string        `yaml:"system_user_api_key" env:"SYSTEM_USER_API_KEY"`
-	AdminUserID       string        `yaml:"admin_user_id" env:"OCIS_ADMIN_USER_ID"`
+	AdminUserID       string        `yaml:"admin_user_id" env:"OCIS_ADMIN_USER_ID" desc:"ID of a user, that should receive admin privileges."`
 }