# lakeFS Server Configuration

Configuring lakeFS is done using a YAML configuration file and/or environment variable. The configuration file's location can be set with the '--config' flag. If not specified, the first file found in the following order will be used:

1. `./config.yaml`
2. `$HOME/lakefs/config.yaml`
3. `/etc/lakefs/config.yaml`
4. `$HOME/.lakefs.yaml`

Configuration items can each be controlled by an environment variable. The variable name will have a prefix of `LAKEFS_`, followed by the name of the configuration, replacing every `.` with a `_`.

> [!NOTE]
>
> **Example**
>
> `LAKEFS_LOGGING_LEVEL` controls `logging.level`.

This reference uses `.` to denote the nesting of values.

## Reference

- `listen_address` `(string : "0.0.0.0:8000")` - A `<host>:<port>` structured string representing the address to listen on

### logging

- `logging.format` `(one of ["json", "text"] : "text")` - Format to output log message in
- `logging.level` `(one of ["TRACE", "DEBUG", "INFO", "WARN", "ERROR", "NONE"] : "INFO")` - Logging level to output
- `logging.audit_log_level` `(one of ["TRACE", "DEBUG", "INFO", "WARN", "ERROR", "NONE"] : "DEBUG")` - Audit logs level to output.

  > **Note**
  >
  > In case you configure this field to be lower than the main logger level, you won't be able to get the [audit logs](<https://docs.lakefs.io/admin/auditing/index.md>)
- `logging.output` `(string : "-")` - A path or paths to write logs to. A `-` means the standard output, `=` means the standard error.
- `logging.file_max_size_mb` `(int : 100)` - Output file maximum size in megabytes.
- `logging.files_keep` `(int : 0)` - Number of log files to keep, default is all.

### actions

- `actions.enabled` `(bool : true)` - Setting this to false will block hooks from being executed.
- `actions.lua.net_http_enabled` `(bool : false)` - Setting this to true will load the `net/http` package.
- `actions.env.enabled` `(bool : true)` - Environment variables accessible by hooks, disabled values evaluated to empty strings
- `actions.env.prefix` `(string : "LAKEFSACTION_")` - Access to environment variables is restricted to those with the prefix. When environment access is enabled and no prefix is provided, all variables are accessible.
- `actions.network.blocked_addresses` `([]string : [])` - Blocks hooks (webhook, Airflow and the Lua `net/http`, `aws`, `azure` and `databricks` packages) from sending HTTP requests to these IP addresses or CIDR ranges. Enforced on every connection, including redirects, without using proxy environment variables. Empty by default, blocking nothing.

### database

Configuration section for the lakeFS key-value store database.

- `database.type` `(string ["postgres"|"dynamodb"|"cosmosdb"|"redis"|"local"] : )` - lakeFS database type

  > **Note**
  >
  > The `redis` database type is available in **lakeFS Enterprise**

- `database.postgres.connection_string` `(string : "postgres://localhost:5432/postgres?sslmode=disable")` - PostgreSQL connection string to use
- `database.postgres.max_open_connections` `(int : 25)` - Maximum number of open connections to the database
- `database.postgres.max_idle_connections` `(int : 25)` - Maximum number of connections in the idle connection pool
- `database.postgres.connection_max_lifetime` `(duration : 5m)` - Sets the maximum amount of time a connection may be reused `(valid units: ns|us|ms|s|m|h)`

- `database.dynamodb.table_name` `(string : "kvstore")` - Table used to store the data
- `database.dynamodb.scan_limit` `(int : 1025)` - Maximal number of items per page during scan operation

  > **Note**
  >
  > Refer to the following [AWS documentation](<https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.Limit>) for further information
- `database.dynamodb.endpoint` `(string : )` - Endpoint URL for database instance
- `database.dynamodb.aws_region` `(string : )` - AWS Region of database instance
- `database.dynamodb.aws_profile` `(string : )` - AWS named profile to use
- `database.dynamodb.aws_access_key_id` `(string : )` - AWS access key ID
- `database.dynamodb.aws_secret_access_key` `(string : )` - AWS secret access key

  > **Note**
  >
  > `endpoint` `aws_region` `aws_access_key_id` `aws_secret_access_key` are not required and used mainly for experimental purposes when working with DynamoDB with different AWS credentials.
- `database.dynamodb.health_check_interval` `(duration : 0s)` - Interval to run health check for the DynamoDB instance (won't run if equal to 0).
- `database.dynamodb.max_attempts` `(int : 10)` - The maximum number of attempts to perform on a DynamoDB request
- `database.dynamodb.max_connections` `(int : 0)` - The maximum number of connections to DynamoDB. 0 means no limit.
- `database.dynamodb.credentials_cache_expiry_window` `(duration : 200s)` - The expiry window for cached AWS credentials. This controls how long before credentials expire that the SDK will attempt to refresh them.
- `database.dynamodb.credentials_cache_expiry_window_jitter_fraction` `(float : 0.5)` - The jitter fraction (0.0-1.0) for credentials cache expiry. This adds randomness to prevent thundering herd effects when refreshing credentials. A value of 0.5 means up to 50% jitter.

- `database.cosmosdb.key` `(string : "")` - If specified, will be used to authenticate to the CosmosDB account. Otherwise, Azure SDK default authentication (with env vars) will be used.
- `database.cosmosdb.endpoint` `(string : "")` - CosmosDB account endpoint, e.g. `https://<account>.documents.azure.com/`.
- `database.cosmosdb.database` `(string : "")` - CosmosDB database name.
- `database.cosmosdb.container` `(string : "")` - CosmosDB container name.
- `database.cosmosdb.throughput` `(int32 : )` - CosmosDB container's RU/s. If not set - the default CosmosDB container throughput is used.
- `database.cosmosdb.autoscale` `(bool : false)` - If set, CosmosDB container throughput is autoscaled (See CosmosDB docs for minimum throughput requirement). Otherwise, uses "Manual" mode ([Docs](<https://learn.microsoft.com/en-us/azure/cosmos-db/provision-throughput-autoscale>)).

- `database.local.path` `(string : "~/lakefs/metadata")` - Local path on the filesystem to store embedded KV metadata, like branches and uncommitted entries
- `database.local.sync_writes` `(bool: true)` - Ensure each write is written to the disk. Disable to increase performance
- `database.local.prefetch_size` `(int: 256)` - How many items to prefetch when iterating over embedded KV records
- `database.local.enable_logging` `(bool: false)` - Enable trace logging for local driver

### auth

- `auth.login_duration` `(time duration : "168h")` - The duration the login token is valid for.
- ~~`auth.login_max_duration`~~ `(time duration : "336h")` - The maximum duration user can ask for a login token.

  > **Deprecated**
  >
  > Only logins through the external principals API could ask for a custom token duration, and lakeFS Community no longer serves that API, so the key is ignored and a warning is logged when it is set. lakeFS Enterprise documents it under [`auth`](<https://docs.lakefs.io/reference/enterprise-configuration/index.md#auth>).

#### auth.cache

- `auth.cache.enabled` `(bool : true)` - Whether to cache access credentials and user policies in-memory. Can greatly improve throughput when enabled.
- `auth.cache.size` `(int : 1024)` - How many items to store in the auth cache. Systems with a very high user count should use a larger value at the expense of \~1kb of memory per cached user.
- `auth.cache.ttl` `(time duration : "20s")` - How long to store an item in the auth cache. Using a higher value reduces load on the database, but will cause changes longer to take effect for cached users.
- `auth.cache.jitter` `(time duration : "3s")` - A random amount of time between 0 and this value is added to each item's TTL. This is done to avoid a large bulk of keys expiring at once and overwhelming the database.

#### auth.encrypt

- `auth.encrypt.secret_key` `(string : "" - required)` - A random (cryptographically safe) generated string that is used for encryption and HMAC signing.

  > **Warning**
  >
  > It is best to keep this somewhere safe such as KMS or Hashicorp Vault, and provide it to the system at run time.

#### auth.api

> [!WARNING]
>
> **Deprecated**
>
> lakeFS Community no longer connects to an external authorization service. The keys below are still accepted so that existing configuration files keep loading, and a warning is logged for each key that is set. None of them selects a service any more, although `auth.api.endpoint` is still read at startup to recognize an installation whose users lived outside lakeFS, as described under [Access Control in lakeFS Community](<https://docs.lakefs.io/security/access-control-lists/index.md#migrating-an-installation-with-multiple-users>). Role-based access control is available in [lakeFS Enterprise](<https://docs.lakefs.io/security/rbac/index.md>).
>
> - ~~`auth.api.endpoint`~~ `(string : "")` - URL of the external authorization service.
> - ~~`auth.api.token`~~ `(string : "")` - API token used to authenticate requests to the external authorization service.
> - ~~`auth.api.supports_invites`~~ `(bool : false)` - Whether the external authorization service supports inviting users by email.
> - ~~`auth.api.health_check_timeout`~~ `(time duration : "")` - Timeout of the external authorization service health check.
> - ~~`auth.api.skip_health_check`~~ `(bool : false)` - Skip the external authorization service health check.

#### auth.authentication\_api

> [!WARNING]
>
> **Deprecated**
>
> lakeFS Community authenticates users only against its built-in database and does not connect to an external authentication service. The keys below are still accepted so that existing configuration files keep loading, but their values are ignored and a warning is logged for each key that is set. lakeFS Enterprise documents them under [`auth.authentication_api`](<https://docs.lakefs.io/reference/enterprise-configuration/index.md#authauthentication_api>).
>
> - ~~`auth.authentication_api.endpoint`~~ `(string : "")` - URL of the external authentication service.
> - ~~`auth.authentication_api.external_principals_enabled`~~ `(bool : false)` - Enable the external principals API.

#### auth.remote\_authenticator

> [!WARNING]
>
> **Deprecated**
>
> lakeFS Community does not delegate the login form to a remote authenticator, so the keys below are ignored and a warning is logged for each key that is set. The [Remote Authenticator](<https://docs.lakefs.io/security/remote-authenticator/index.md>) is available in lakeFS Enterprise, which documents the keys under [`auth.remote_authenticator`](<https://docs.lakefs.io/reference/enterprise-configuration/index.md#authremote_authenticator>).
>
> - ~~`auth.remote_authenticator.enabled`~~ `(bool : false)` - Also authenticate users via a Remote Authenticator server.
> - ~~`auth.remote_authenticator.endpoint`~~ `(string : "")` - Endpoint URL of the remote authentication service.
> - ~~`auth.remote_authenticator.default_user_group`~~ `(string : "Viewers")` - Group in which remotely authenticated users are created.
> - ~~`auth.remote_authenticator.request_timeout`~~ `(time duration : 10s)` - Timeout for remote authentication requests.

#### auth.oidc

> [!WARNING]
>
> **Deprecated**
>
> lakeFS Community does not accept OIDC sessions, so the keys below are ignored and a warning is logged for each key that is set. [Single sign-on](<https://docs.lakefs.io/security/sso/index.md>) is available in lakeFS Enterprise, which documents the keys under [`auth.oidc`](<https://docs.lakefs.io/reference/enterprise-configuration/index.md#authoidc>).
>
> - ~~`auth.oidc.default_initial_groups`~~ `(string[] : [])` - Groups assigned to OIDC users by default.
> - ~~`auth.oidc.initial_groups_claim_name`~~ `(string : "")` - ID token claim that provides the initial groups for new users.
> - ~~`auth.oidc.friendly_name_claim_name`~~ `(string : "")` - ID token claim used as the user's display name.
> - ~~`auth.oidc.persist_friendly_name`~~ `(bool : false)` - Persist the display name to the KV store.
> - ~~`auth.oidc.validate_id_token_claims`~~ `(map[string]string : {})` - Claims and values that the ID token must contain.

#### auth.cookie\_auth\_verification

> [!WARNING]
>
> **Deprecated**
>
> lakeFS Community does not accept sessions set by an external identity provider, so the keys below are ignored and a warning is logged for each key that is set. [Single sign-on](<https://docs.lakefs.io/security/sso/index.md>) is available in lakeFS Enterprise, which documents the keys under [`auth.cookie_auth_verification`](<https://docs.lakefs.io/reference/enterprise-configuration/index.md#authcookie_auth_verification>).
>
> - ~~`auth.cookie_auth_verification.validate_id_token_claims`~~ `(map[string]string : {})` - Claims and values that the ID token must contain.
> - ~~`auth.cookie_auth_verification.default_initial_groups`~~ `(string[] : [])` - Groups assigned to users by default.
> - ~~`auth.cookie_auth_verification.initial_groups_claim_name`~~ `(string : "")` - ID token claim that provides the initial groups for new users.
> - ~~`auth.cookie_auth_verification.friendly_name_claim_name`~~ `(string : "")` - ID token claim used as the user's display name.
> - ~~`auth.cookie_auth_verification.persist_friendly_name`~~ `(bool : false)` - Persist the display name to the KV store.
> - ~~`auth.cookie_auth_verification.external_user_id_claim_name`~~ `(string : "")` - ID token claim used as the user's identifier.
> - ~~`auth.cookie_auth_verification.auth_source`~~ `(string : "")` - Label recorded as the authentication source of the user.

#### auth.ui\_config

- `auth.ui_config.login_failed_message` `(string : "The credentials don't match.")` - Custom error message displayed when authentication fails on the login form.

> [!WARNING]
>
> **Deprecated**
>
> lakeFS Community serves a single login form for the built-in administrator credentials and runs without an RBAC authorization service, so the keys below are ignored and a warning is logged for each key that is set. See [Access Control in lakeFS Community](<https://docs.lakefs.io/security/access-control-lists/index.md>). Single sign-on and [Role-Based Access Control](<https://docs.lakefs.io/security/rbac/index.md>) are available in lakeFS Enterprise, which documents the keys under [`auth.ui_config`](<https://docs.lakefs.io/reference/enterprise-configuration/index.md#authui_config>).
>
> - ~~`auth.ui_config.rbac`~~ `(string : "")` - The authorization mode of the web UI.
> - ~~`auth.ui_config.login_url`~~ `(string : "")` - An absolute or relative URL to your IdP’s login page, used to authenticate to lakeFS via SSO with OIDC or SAML.
> - ~~`auth.ui_config.logout_url`~~ `(string : "")` - URL to redirect users to when they log out from lakeFS.
> - ~~`auth.ui_config.use_login_placeholders`~~ `(bool : false)` - Show *Username* and *Password* placeholders on the login form instead of *Access Key ID* and *Secret Access Key*.

### blockstore

- `blockstore.type` `(one of ["local", "s3", "gs", "azure", "mem"] : required)`. Block adapter to use. This controls where the underlying data will be stored
- `blockstore.default_namespace_prefix` `(string : )` - Use this to help your users choose a storage namespace for their repositories. If specified, the storage namespace will be filled with this default value as a prefix when creating a repository from the UI. The user may still change it to something else.
- `blockstore.signing.secret_key` `(string : required)` - A random generated string that is used for HMAC signing when using get/link physical address

> [!NOTE]
>
> local blockstore is supported for POSIX compliant filesystems only.

- `blockstore.local.path` `(string: "~/lakefs/data/block")` - When using the local Block Adapter, which directory to store files in
- `blockstore.local.import_enabled` `(bool: false)` - Enable import for local Block Adapter, relevant only if you are using shared location
- `blockstore.local.import_hidden` `(bool: false)` - When enabled import will scan and import any file or folder that starts with a dot character.
- `blockstore.local.allowed_external_prefixes` `([]string: [])` - List of absolute path prefixes used to match any access for external location (ex: /var/data/). Empty list mean no access to external location.

- `blockstore.s3.region` `(string : "us-east-1")` - Default region for lakeFS to use when interacting with S3.
- `blockstore.s3.profile` `(string : )` - If specified, will be used as a [named credentials profile](<https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles>)
- `blockstore.s3.credentials_file` `(string : )` - If specified, will be used as a [credentials file](<https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html>)
- `blockstore.s3.credentials.access_key_id` `(string : )` - If specified, will be used as a static set of credential
- `blockstore.s3.credentials.secret_access_key` `(string : )` - If specified, will be used as a static set of credential
- `blockstore.s3.credentials.session_token` `(string : )` - If specified, will be used as a static session token
- `blockstore.s3.endpoint` `(string : )` - If specified, custom endpoint for the AWS S3 API (https://s3\_compatible\_service\_endpoint:port)
- `blockstore.s3.force_path_style` `(bool : false)` - When true, use path-style S3 URLs (https:/// instead of https://.)
- `blockstore.s3.discover_bucket_region` `(bool : true)` - (Can be turned off if the underlying S3 bucket doesn't support the GetBucketRegion API).
- `blockstore.s3.skip_verify_certificate_test_only` `(bool : false)` - Skip certificate verification while connecting to the storage endpoint. Should be used only for testing.
- `blockstore.s3.server_side_encryption` `(string : )` - Server side encryption format used (Example on AWS using SSE-KMS while passing "aws:kms")
- `blockstore.s3.server_side_encryption_kms_key_id` `(string : )` - Server side encryption KMS key ID
- `blockstore.s3.pre_signed_expiry` `(time duration : "15m")` - Expiry of pre-signed URL.
- `blockstore.s3.pre_signed_endpoint` `(string : )` - Custom endpoint for pre-signed URLs.
- `blockstore.s3.disable_pre_signed` `(bool : false)` - Disable use of pre-signed URL.
- `blockstore.s3.disable_pre_signed_ui` `(bool : true)` - Disable use of pre-signed URL in the UI.
- `blockstore.s3.disable_pre_signed_multipart` `(bool : )` - Disable use of pre-signed multipart upload **experimental**, enabled on s3 block adapter with presign support.
- `blockstore.s3.client_log_request` `(bool : false)` - Set SDK logging bit to log requests
- `blockstore.s3.client_log_retries` `(bool : false)` - Set SDK logging bit to log retries

- `blockstore.azure.storage_account` `(string : )` - If specified, will be used as the Azure storage account
- `blockstore.azure.storage_access_key` `(string : )` - If specified, will be used as the Azure storage access key
- `blockstore.azure.pre_signed_expiry` `(time duration : "15m")` - Expiry of pre-signed URL.
- `blockstore.azure.disable_pre_signed` `(bool : false)` - Disable use of pre-signed URL.
- `blockstore.azure.disable_pre_signed_ui` `(bool : true)` - Disable use of pre-signed URL in the UI.
- ~~`blockstore.azure.china_cloud`~~ `(bool : false)` - Enable for using lakeFS on Azure China Cloud.

  > **Deprecated**
  >
  > Please use `blockstore.azure.domain`
- `blockstore.azure.domain` `(string : blob.core.windows.net)` - Enables support of different Azure cloud domains.

  Current supported domains (in Beta stage): \[`blob.core.chinacloudapi.cn`, `blob.core.usgovcloudapi.net`\]

- `blockstore.gs.credentials_file` `(string : )` - If specified will be used as a file path of the JSON file that contains your Google service account key
- `blockstore.gs.credentials_json` `(string : )` - If specified will be used as JSON string that contains your Google service account key (when credentials\_file is not set)
- `blockstore.gs.data_credentials_file` `(string : )` - If specified will be used as a file path of the JSON file that contains your Google service account key for data operations **experimental**
- `blockstore.gs.data_credentials_json` `(string : )` - If specified will be used as JSON string that contains your Google service account key for data operations **experimental**
- `blockstore.gs.pre_signed_expiry` `(time duration : "15m")` - Expiry of pre-signed URL.
- `blockstore.gs.disable_pre_signed` `(bool : false)` - Disable use of pre-signed URL.
- `blockstore.gs.disable_pre_signed_ui` `(bool : true)` - Disable use of pre-signed URL in the UI.
- `blockstore.gs.server_side_encryption_customer_supplied` `(string : )` - Server side encryption with AES key in hex format, exclusive with key ID below
- `blockstore.gs.server_side_encryption_kms_key_id` `(string : )` - Server side encryption KMS key ID, exclusive with above

### graveler

- `graveler.ensure_readable_root_namespace` `(bool: true)` - When creating a new repository use this to verify that lakeFS has access to the root of the underlying storage namespace. Set `false` only if lakeFS should not have access (i.e pre-sign mode only).
- `graveler.max_batch_delay` `(duration : 3ms)` - Controls the server batching period for references store operations.
- `graveler.background.rate_limit` `(int : 0)` - Requests per seconds limit on background work performed (default: 0 - unlimited), like deleting committed staging tokens.

#### graveler.repository\_cache

- `graveler.repository_cache.size` `(int : 1000)` - How many items to store in the repository cache.
- `graveler.repository_cache.ttl` `(time duration : "5s")` - How long to store an item in the repository cache.
- `graveler.repository_cache.jitter` `(time duration : "2s")` - A random amount of time between 0 and this value is added to each item's TTL.

#### graveler.commit\_cache

- `graveler.commit_cache.size` `(int : 50000)` - How many items to store in the commit cache.
- `graveler.commit_cache.ttl` `(time duration : "10m")` - How long to store an item in the commit cache.
- `graveler.commit_cache.jitter` `(time duration : "2s")` - A random amount of time between 0 and this value is added to each item's TTL.

### committed

- `committed.block_storage_prefix` (`string` : `_lakefs`) - Prefix for metadata file storage in each repository's storage namespace
- `committed.sstable.memory.cache_size_bytes` (`int` : `400_000_000`) - maximal size of in-memory cache used for each SSTable reader.

#### committed.local\_cache

An object describing the local (on-disk) cache of metadata from permanent storage.

- `committed.local_cache.size_bytes` (`int` : `1073741824`) - bytes for local cache to use on disk. The cache may use more storage for short periods of time.
- `committed.local_cache.dir` (`string`, `~/lakefs/data/cache`) - directory to store local cache.
- `committed.local_cache.range_proportion` (`float` : `0.9`) - proportion of local cache to use for storing ranges (leaves of committed metadata storage).
- `committed.local_cache.range.open_readers` (`int` : `500`) - maximal number of unused open SSTable readers to keep for ranges.
- `committed.local_cache.range.num_shards` (`int` : `30`) - sharding factor for open SSTable readers for ranges. Should be at least `sqrt(committed.local_cache.range.open_readers)`.
- `committed.local_cache.metarange_proportion` (`float` : `0.1`) - proportion of local cache to use for storing metaranges (roots of committed metadata storage).
- `committed.local_cache.metarange.open_readers` (`int` : `50`) - maximal number of unused open SSTable readers to keep for metaranges.
- `committed.local_cache.metarange.num_shards` (`int` : `10`) - sharding factor for open SSTable readers for metaranges. Should be at least `sqrt(committed.local_cache.metarange.open_readers)`.

#### committed.permanent

- `committed.permanent.min_range_size_bytes` (`int` : `0`) - Smallest allowable range in metadata. Increase to somewhat reduce random access time on committed metadata, at the cost of increased committed metadata storage cost.
- `committed.permanent.max_range_size_bytes` (`int` : `20971520`) - Largest allowable range in metadata. Should be close to the size at which fetching from remote storage becomes linear.
- `committed.permanent.range_raggedness_entries` (`int` : `50_000`) - Average number of object pointers to store in each range (subject to `min_range_size_bytes` and `max_range_size_bytes`).

### email

- `email.smtp_host` `(string)` - A string representing the URL of the SMTP host.
- `email.smtp_port` (`int`) - An integer representing the port of the SMTP service (465, 587, 993, 25 are some standard ports)
- `email.use_ssl` (`bool : false`) - Use SSL connection with SMTP host.
- `email.username` `(string)` - A string representing the username of the specific account at the SMTP. It's recommended to provide this value at runtime from a secret vault of some sort.
- `email.password` `(string)` - A string representing the password of the account. It's recommended to provide this value at runtime from a secret vault of some sort.
- `email.local_name` `(string)` - A string representing the hostname sent to the SMTP server with the HELO command. By default, "localhost" is sent.
- `email.sender` `(string)` - A string representing the email account which is set as the sender.
- `email.limit_every_duration` `(duration : 1m)` - The average time between sending emails. If zero is entered, there is no limit to the amount of emails that can be sent.
- `email.burst` `(int: 10)` - Maximal burst of emails before applying `limit_every_duration`. The zero value means no burst and therefore no emails can be sent.
- `email.lakefs_base_url` `(string : "http://localhost:8000")` - A string representing the base lakeFS endpoint to be directed to when emails are sent inviting users, reseting passwords etc.

### gateways

- `gateways.s3.domain_name` `(string : "s3.local.lakefs.io")` - a FQDN representing the S3 endpoint used by S3 clients to call this server (`*.s3.local.lakefs.io` always resolves to 127.0.0.1, useful for local development, if using [virtual-host addressing](<https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html>).
- `gateways.s3.region` `(string : "us-east-1")` - AWS region we're pretending to be in, it should match the region configuration used in AWS SDK clients
- `gateways.s3.fallback_url` `(string)` - If specified, requests with a non-existing repository will be forwarded to this URL. This can be useful for using lakeFS side-by-side with S3, with the URL pointing at an [S3Proxy](<https://github.com/gaul/s3proxy>) instance. When `gateways.s3.resolve_tenant` is enabled, only requests that resolve to the root tenant can reach the fallback, because a tenant-addressed bucket name is unambiguously a lakeFS address.
- `gateways.s3.resolve_tenant` `(bool : false)` - When enabled, the S3 gateway resolves the [tenant](<https://docs.lakefs.io/security/tenants/index.md>) from the bucket name: a name of the form `{tenant}--{repository}` addresses that repository inside that tenant, and a bare name addresses the reserved `root` tenant. While disabled, every bucket name is taken whole and every request operates on `root`. Requires lakeFS Enterprise with tenants licensed.
- `gateways.s3.sts.enabled` `(bool : true)` - When enabled, lakeFS serves the STS `AssumeRoleWithWebIdentity` action, which exchanges a lakeFS login token or a [JWT Login](<https://docs.lakefs.io/security/jwt-login/index.md>) identity provider token for [temporary S3 Gateway credentials](<https://docs.lakefs.io/security/s3-temporary-credentials/index.md>), and the S3 Gateway accepts those credentials.
- `gateways.s3.verify_unsupported` `(bool : true)` - The S3 gateway errors on unsupported requests, but when disabled, defers to target-based handlers.

### tls

- `tls.enabled` `(bool :false)` - Enable TLS listening. The `listen_address` will be used to serve HTTPS requests. (mainly for local development)
- `tls.cert_file` `(string : )` - Server certificate file path used while serve HTTPS (.cert or .crt file - signed certificates).
- `tls.key_file` `(string : )` - Server secret key file path used whie serve HTTPS (.key file - private key).

### stats

The server sends usage statistics to an external host. See [Outbound Connections and Air-Gapped Deployments](<https://docs.lakefs.io/admin/outbound-connections/index.md#usage-statistics>) for what they contain.

- `stats.enabled` `(bool : true)` - Whether to periodically send usage statistics
- `stats.address` `(string : "https://stats.lakefs.io")` - Base URL that usage statistics are sent to
- `stats.flush_interval` `(duration : 30s)` - Interval used to post collected usage statistics
- `stats.flush_size` `(int : 100)` - Number of collected records that triggers a post
- `stats.extended` `(bool : false)` - Include repository names, branch names, and user identifiers in usage statistics, each replaced by a hash of its value. Defaults to `true` in lakeFS Enterprise.

### installation

- `installation.user_name` `(string : )` - When specified, an initial admin user will be created when the server is first run. Works only when `database.type` is set to local. Requires `installation.access_key_id` and `installation.secret_access_key`.
- `installation.access_key_id` `(string : )` - Admin's initial access key id (used once in the initial setup process)
- `installation.secret_access_key` `(string : )` - Admin's initial secret access key (used once in the initial setup process)
- `installation.allow_inter_region_storage` `(bool : true)` - Allow storage in a different region than the one the server is running in.

### usage\_report

- `usage_report.enabled` `(bool : true)` - Store API and Gateway usage reports into key-value store.
- `usage_report.flush_interval` `(duration : 5m)` - Sets interval for flushing in-memory usage data to key-value store.

### ui

- `ui.enabled` `(bool: true)` - Whether to serve the embedded UI from the binary

### security

The server contacts external hosts to check for security advisories and new releases. See [Outbound Connections and Air-Gapped Deployments](<https://docs.lakefs.io/admin/outbound-connections/index.md>) for what each check sends.

- `security.audit_check_url` `(string : "https://audit.lakefs.io/audit")` - URL of the security advisory check. Set to `""` in the configuration file to turn the check off; an empty environment variable is ignored.
- `security.audit_check_interval` `(duration : 24h)` - Interval between security advisory checks
- `security.check_latest_version` `(bool : true)` - Whether to look up the latest lakeFS release on `api.github.com` to report available upgrades
- `security.check_latest_version_cache` `(duration : 1h)` - How long the result of the latest release lookup is cached

### garbage collection

- `ugc.prepare_max_file_size` `(int: 125829120)` - Uncommitted garbage collection prepare request, limit the produced file maximum size
- `ugc.prepare_interval` `(duraction: 1m)` - Uncommitted garbage collection prepare request, limit produce time to interval

### branch\_lifecycle

See [Branch Lifecycle](<https://docs.lakefs.io/guides/branch-lifecycle/index.md>) for full feature details.

- `branch_lifecycle.schedule` `(string : "0 * * * *")` - Cron schedule for the job that applies repository [branch lifecycle policies](<https://docs.lakefs.io/guides/branch-lifecycle/index.md>). The job is always wired; control whether it acts on a repository by setting or clearing that repository's policies.

### object\_lifecycle

See [Object Lifecycle](<https://docs.lakefs.io/data-retention/object-lifecycle/index.md>) for full feature details.

- `object_lifecycle.schedule` `(string : "0 2 * * *")` - Cron schedule for the job that applies repository [object lifecycle rules](<https://docs.lakefs.io/data-retention/object-lifecycle/index.md>). The job is always wired; control whether it acts on a repository by setting or clearing that repository's rules.
- `object_lifecycle.workers` `(int : 1)` - Number of branches evaluated concurrently within a single run.

## Using Environment Variables

All the configuration variables can be set or overridden using environment variables.

To set an environment variable, prepend `LAKEFS_` to its name, convert it to upper case, and replace `.` with `_`:

For example, `logging.format` becomes `LAKEFS_LOGGING_FORMAT`, `blockstore.s3.region` becomes `LAKEFS_BLOCKSTORE_S3_REGION`, etc.

To set a value into a `map[string]string` type field, use the syntax `key1=value1,key2=value2,...`

An environment variable set to an empty value is ignored, so a setting that must be set to an empty string, such as `security.audit_check_url`, has to be set in the configuration file.

## Example Configurations

> [!NOTE]
>
> **Local Development with PostgreSQL database**
>
> ```yaml
> ---
> listen_address: "0.0.0.0:8000"
>
> database:
> type: "postgres"
> postgres:
>     connection_string: "postgres://localhost:5432/postgres?sslmode=disable"
>
> logging:
> format: text
> level: DEBUG
> output: "-"
>
> auth:
> encrypt:
>     secret_key: "10a718b3f285d89c36e9864494cdd1507f3bc85b342df24736ea81f9a1134bcc"
>
> blockstore:
> type: local
> local:
>     path: "~/lakefs/dev/data"
>
> gateways:
> s3:
>     region: us-east-1
> ```

> [!NOTE]
>
> **AWS Deployment with DynamoDB database**
>
> ```yaml
> ---
> logging:
> format: json
> level: WARN
> output: "-"
>
> database:
> type: "dynamodb"
> dynamodb:
>     table_name: "kvstore"
>
> auth:
> encrypt:
>     secret_key: "10a718b3f285d89c36e9864494cdd1507f3bc85b342df24736ea81f9a1134bcc"
>
> blockstore:
> type: s3
> s3:
>     region: us-east-1 # optional, fallback in case discover from bucket is not supported
>     credentials_file: /secrets/aws/credentials
>     profile: default
> ```

> [!NOTE]
>
> **Google Storage**
>
> ```yaml
> ---
> logging:
> format: json
> level: WARN
> output: "-"
>
> database:
> type: "postgres"
> postgres:
>     connection_string: "postgres://user:pass@lakefs.rds.amazonaws.com:5432/postgres"
>
> auth:
> encrypt:
>     secret_key: "10a718b3f285d89c36e9864494cdd1507f3bc85b342df24736ea81f9a1134bcc"
>
> blockstore:
> type: gs
> gs:
>     credentials_file: /secrets/lakefs-service-account.json
> ```

> [!NOTE]
>
> **MinIO**
>
> ```yaml
> ---
> logging:
> format: json
> level: WARN
> output: "-"
>
> database:
> type: "postgres"
> postgres:
>     connection_string: "postgres://user:pass@lakefs.rds.amazonaws.com:5432/postgres"
>
> auth:
> encrypt:
>     secret_key: "10a718b3f285d89c36e9864494cdd1507f3bc85b342df24736ea81f9a1134bcc"
>
> blockstore:
> type: s3
> s3:
>     force_path_style: true
>     endpoint: http://localhost:9000
>     discover_bucket_region: false
>     credentials:
>         access_key_id: minioadmin
>         secret_access_key: minioadmin
> ```

> [!NOTE]
>
> **Azure blob storage**
>
> ```yaml
> ---
> logging:
> format: json
> level: WARN
> output: "-"
>
> database:
> type: "cosmosdb"
> cosmosdb:
>     key: "ExampleReadWriteKeyMD7nkPOWgV7d4BUjzLw=="
>     endpoint: "https://lakefs-account.documents.azure.com:443/"
>     database: "lakefs-db"
>     container: "lakefs-container"
>
> auth:
> encrypt:
>     secret_key: "10a718b3f285d89c36e9864494cdd1507f3bc85b342df24736ea81f9a1134bcc"
>
> blockstore:
> type: azure
> azure:
>     storage_account: exampleStorageAcount
>     storage_access_key: ExampleAcessKeyMD7nkPOWgV7d4BUjzLw==
> ```
