/usr/bin/versitygw

NAME:
   versitygw - Versity S3 Gateway

USAGE:
   versitygw [global options] command [command options]

DESCRIPTION:
   The Versity S3 Gateway is an S3 protocol translator that allows an S3 client
   to access the supported backend storage as if it was a native S3 service.
   VersityGW is an open-source project licensed under the Apache 2.0 License. The
   source code is hosted on GitHub at https://github.com/versity/versitygw, and
   documentation can be found in the GitHub wiki.

COMMANDS:
   posix    posix filesystem storage backend
   scoutfs  scoutfs filesystem storage backend
   s3       s3 storage backend
   azure    azure blob storage backend
   plugin   load a backend from a plugin
   iam      IAM API server
   admin    admin CLI tool
   test     Client side testing command for the gateway
   utils    utility helper CLI tool
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --version, -v                                                      list versitygw version (default: false)
   --port value, -p value [ --port value, -p value ]                  gateway listen address: <ip>:<port>, :<port>, /path/to/socket for file-backed UNIX sockets, or @name for Linux abstract namespace sockets (can be specified multiple times for listening on multiple addresses) (default: ":7070") [$VGW_PORT]
   --webui value [ --webui value ]                                    enable WebUI server on the specified listen address (e.g. ':7071', '127.0.0.1:7071', 'localhost:7071', '/run/vgw/webui.sock'; supports the same UNIX socket forms as --port; can be specified multiple times for listening on multiple addresses; disabled when omitted) [$VGW_WEBUI_PORT]
   --webui-cert value                                                 TLS cert file for WebUI (defaults to --cert value when WebUI is enabled) [$VGW_WEBUI_CERT]
   --webui-key value                                                  TLS key file for WebUI (defaults to --key value when WebUI is enabled) [$VGW_WEBUI_KEY]
   --webui-no-tls                                                     disable TLS for WebUI even if TLS is configured for the gateway (default: false) [$VGW_WEBUI_NO_TLS]
   --webui-gateways value [ --webui-gateways value ]                  override auto-detected S3 gateway URLs for WebUI (e.g. 'http://localhost:7070', 'https://s3.example.com'; can be specified multiple times) [$VGW_WEBUI_GATEWAYS]
   --webui-admin-gateways value [ --webui-admin-gateways value ]      override auto-detected admin gateway URLs for WebUI (e.g. 'http://localhost:7080', 'https://admin.example.com'; can be specified multiple times) [$VGW_WEBUI_ADMIN_GATEWAYS]
   --webui-iam-gateways value [ --webui-iam-gateways value ]          standalone IAM service URLs offered to the WebUI login page (e.g. 'http://localhost:7076', 'https://iam.example.com'; can be specified multiple times). Not auto-detected from an S3 gateway: the IAM service is a separate process. Setting this also tells the WebUI that the standalone IAM service, not the admin API, manages this deployment: the admin endpoint is ignored entirely (hidden from the login page along with every admin-API surface), and the management pages run on the S3 and IAM APIs alone [$VGW_WEBUI_IAM_GATEWAYS]
   --webui-path-prefix value                                          mount the WebUI under a path prefix (e.g. '/ui'); must be single segment path that starts with '/' [$VGW_WEBUI_PATH_PREFIX]
   --webui-s3-prefix value                                            mount the WebUI on the S3 port at the given path prefix (e.g. '/ui'); must start with '/', must not be '/', and must not end with '/' [$VGW_WEBUI_S3_PREFIX]
   --website value [ --website value ]                                enable static website hosting endpoint on the specified listen address (e.g. ':8080'; same forms as --port; can be specified multiple times; requires --website-domain) [$VGW_WEBSITE_PORT]
   --website-domain value                                             base domain for website virtual-host routing (e.g. 'example.com'); host 'blog.example.com' serves bucket 'blog', host 'example.com' serves bucket 'example.com'; when omitted the full hostname is used as the bucket name (catch-all mode, buckets named as FQDNs) [$VGW_WEBSITE_DOMAIN]
   --website-cert value                                               TLS cert file for website endpoint (defaults to --cert value when website is enabled) [$VGW_WEBSITE_CERT]
   --website-key value                                                TLS key file for website endpoint (defaults to --key value when website is enabled) [$VGW_WEBSITE_KEY]
   --website-no-tls                                                   disable TLS for website endpoint even if TLS is configured for the gateway (default: false) [$VGW_WEBSITE_NO_TLS]
   --access value, -a value                                           root user access key [$ROOT_ACCESS_KEY_ID, $ROOT_ACCESS_KEY]
   --secret value, -s value                                           root user secret access key [$ROOT_SECRET_ACCESS_KEY, $ROOT_SECRET_KEY]
   --region value, -r value                                           s3 region string (default: "us-east-1") [$VGW_REGION]
   --max-connections value, --mc value                                maximum number of concurrent connections s3 api server may serve (default: 250000) [$VGW_MAX_CONNECTIONS]
   --max-requests value, --mr value                                   maximum number of in-flight requests s3 api server may serve (default: 100000) [$VGW_MAX_REQUESTS]
   --cors-allow-origin value                                          default CORS Access-Control-Allow-Origin value (applied when no bucket CORS configuration exists, for admin APIs, and for the standalone IAM API); required on the 'iam' command before a browser-based WebUI on another origin can reach it [$VGW_CORS_ALLOW_ORIGIN]
   --cert value                                                       TLS cert file [$VGW_CERT]
   --key value                                                        TLS key file [$VGW_KEY]
   --admin-port value, --ap value [ --admin-port value, --ap value ]  gateway admin server listen address: <ip>:<port>, :<port>, /path/to/socket for file-backed UNIX sockets, or @name for Linux abstract namespace sockets (can be specified multiple times for listening on multiple addresses) [$VGW_ADMIN_PORT]
   --admin-max-connections value, --amc value                         maximum number of concurrent connections s3 admin server may handle (default: 250000) [$VGW_ADMIN_MAX_CONNECTIONS]
   --admin-max-requests value, --amr value                            maximum number of in-flight requests s3 admin server may handle (default: 100000) [$VGW_ADMIN_MAX_REQUESTS]
   --admin-cert value                                                 TLS cert file for admin server [$VGW_ADMIN_CERT]
   --admin-cert-key value                                             TLS key file for admin server [$VGW_ADMIN_CERT_KEY]
   --admin-path-prefix value                                          mount the admin API under a path prefix (e.g. '/admin'), on --admin-port or, when that is unset, on the S3 port; must be '/' followed by a single segment of letters, digits, '-', '.', '_' or '~' [$VGW_ADMIN_PATH_PREFIX]
   --log-level value                                                  debug logger verbosity: "silent" (default, no debug output), "debug" (full request/response logging with secrets and tokens masked), or "unsafe" (full logging with NO masking -- prints access keys, secrets, session tokens, and signatures in the clear; only use for local troubleshooting, never in production) (default: "silent") [$VGW_LOG_LEVEL]
   --debug                                                            enable debug output (deprecated: use --log-level=debug for finer-grained control) (default: false) [$VGW_DEBUG]
   --pprof value                                                      enable pprof debug on specified port [$VGW_PPROF]
   --keep-alive                                                       enable keep-alive connections (default: false) [$VGW_KEEP_ALIVE]
   --quiet, -q                                                        silence stdout request logging output (default: false) [$VGW_QUIET]
   --virtual-domain value, --vd value                                 enables the virtual host style bucket addressing with the specified arg as the base domain [$VGW_VIRTUAL_DOMAIN]
   --disable-acl, --noacl                                             disables gateway ACLs, by ignoring all ACL headers (default: false) [$VGW_DISABLE_ACL]
   --list-buckets-scope value                                         which buckets ListBuckets returns to non-admin users of an IAM backend without identity policies (internal, LDAP, Vault, IPA, S3): owned (their own buckets, as in AWS), accessible (also buckets whose ACL or bucket policy grants them s3:ListBucket on at least part of the bucket, ignoring public grants; reads the policy of each bucket they don't own on every listing), or all (every bucket). Only owned is allowed with the standalone IAM service (default: "owned") [$VGW_LIST_BUCKETS_SCOPE]
   --disable-sse-c-tls-enforcement                                    allow SSE-C requests over plaintext HTTP (default: false) [$VGW_DISABLE_SSE_C_TLS_ENFORCEMENT]
   --access-log value                                                 enable server access logging to specified file, stdout, stderr, or - for stdout [$LOGFILE, $VGW_ACCESS_LOG]
   --admin-access-log value                                           enable admin server access logging to specified file, stdout, stderr, or - for stdout [$LOGFILE, $VGW_ADMIN_ACCESS_LOG]
   --client-ip-header value                                           header to take the client IP for logs from: "X-Forwarded-For" or "X-Real-Ip"; disabled by default; requires --trusted-proxies [$VGW_CLIENT_IP_HEADER]
   --trusted-proxies value                                            comma-separated IP addresses and CIDR prefixes of the proxies in front of the gateway, or "unix" to trust a peer connected over a unix socket; the client IP header is only honoured from these peers, and is required when --client-ip-header is set [$VGW_TRUSTED_PROXIES]
   --log-webhook-url value                                            webhook url to send the audit logs [$WEBHOOK, $VGW_LOG_WEBHOOK_URL]
   --event-kafka-url value, --eku value                               kafka server url to send the bucket notifications. [$VGW_EVENT_KAFKA_URL]
   --event-kafka-topic value, --ekt value                             kafka server pub-sub topic to send the bucket notifications to [$VGW_EVENT_KAFKA_TOPIC]
   --event-kafka-key value, --ekk value                               kafka server put-sub topic key to send the bucket notifications to [$VGW_EVENT_KAFKA_KEY]
   --event-nats-url value, --enu value                                nats server url to send the bucket notifications [$VGW_EVENT_NATS_URL]
   --event-nats-topic value, --ent value                              nats server pub-sub topic to send the bucket notifications to [$VGW_EVENT_NATS_TOPIC]
   --event-rabbitmq-url value, --eru value                            rabbitmq server url to send the bucket notifications (amqp or amqps scheme) [$VGW_EVENT_RABBITMQ_URL]
   --event-rabbitmq-exchange value, --ere value                       rabbitmq exchange to publish bucket notifications to (blank for default) [$VGW_EVENT_RABBITMQ_EXCHANGE]
   --event-rabbitmq-routing-key value, --errk value                   rabbitmq routing key when publishing bucket notifications (defaults to bucket name when blank) [$VGW_EVENT_RABBITMQ_ROUTING_KEY]
   --event-webhook-url value, --ewu value                             webhook url to send bucket notifications [$VGW_EVENT_WEBHOOK_URL]
   --event-filter value, --ef value                                   bucket event notifications filters configuration file path [$VGW_EVENT_FILTER]
   --iam-dir value                                                    if defined, run internal iam service within this directory [$VGW_IAM_DIR]
   --iam-ldap-url value                                               ldap server url to store iam data [$VGW_IAM_LDAP_URL]
   --iam-ldap-bind-dn value                                           ldap server binding dn, example: 'cn=admin,dc=example,dc=com' [$VGW_IAM_LDAP_BIND_DN]
   --iam-ldap-bind-pass value                                         ldap server user password [$VGW_IAM_LDAP_BIND_PASS]
   --iam-ldap-query-base value                                        ldap server destination query, example: 'ou=iam,dc=example,dc=com' [$VGW_IAM_LDAP_QUERY_BASE]
   --iam-ldap-object-classes value                                    ldap server object classes used to store the data. provide it as comma separated string, example: 'top,person' [$VGW_IAM_LDAP_OBJECT_CLASSES]
   --iam-ldap-access-atr value                                        ldap server user access key id attribute name [$VGW_IAM_LDAP_ACCESS_ATR]
   --iam-ldap-secret-atr value                                        ldap server user secret access key attribute name [$VGW_IAM_LDAP_SECRET_ATR]
   --iam-ldap-role-atr value                                          ldap server user role attribute name [$VGW_IAM_LDAP_ROLE_ATR]
   --iam-ldap-user-id-atr value                                       ldap server user id attribute name [$VGW_IAM_LDAP_USER_ID_ATR]
   --iam-ldap-group-id-atr value                                      ldap server user group id attribute name [$VGW_IAM_LDAP_GROUP_ID_ATR]
   --iam-ldap-project-id-atr value                                    ldap server user project id attribute name [$VGW_IAM_LDAP_PROJECT_ID_ATR]
   --iam-ldap-tls-skip-verify                                         disable TLS certificate verification for LDAP connections (insecure, for self-signed certificates) (default: false) [$VGW_IAM_LDAP_TLS_SKIP_VERIFY]
   --iam-vault-endpoint-url value                                     vault server url [$VGW_IAM_VAULT_ENDPOINT_URL]
   --iam-vault-namespace value                                        vault server namespace [$VGW_IAM_VAULT_NAMESPACE]
   --iam-vault-secret-storage-path value                              vault server secret storage path [$VGW_IAM_VAULT_SECRET_STORAGE_PATH]
   --iam-vault-secret-storage-namespace value                         vault server secret storage namespace [$VGW_IAM_VAULT_SECRET_STORAGE_NAMESPACE]
   --iam-vault-auth-method value                                      vault server auth method [$VGW_IAM_VAULT_AUTH_METHOD]
   --iam-vault-auth-namespace value                                   vault server auth namespace [$VGW_IAM_VAULT_AUTH_NAMESPACE]
   --iam-vault-mount-path value                                       vault server mount path [$VGW_IAM_VAULT_MOUNT_PATH]
   --iam-vault-root-token value                                       vault server root token [$VGW_IAM_VAULT_ROOT_TOKEN]
   --iam-vault-role-id value                                          vault server user role id [$VGW_IAM_VAULT_ROLE_ID]
   --iam-vault-role-secret value                                      vault server user role secret [$VGW_IAM_VAULT_ROLE_SECRET]
   --iam-vault-server_cert value                                      vault server TLS certificate [$VGW_IAM_VAULT_SERVER_CERT]
   --iam-vault-client_cert value                                      vault client TLS certificate [$VGW_IAM_VAULT_CLIENT_CERT]
   --iam-vault-client_cert_key value                                  vault client TLS certificate key [$VGW_IAM_VAULT_CLIENT_CERT_KEY]
   --s3-iam-access value                                              s3 IAM access key [$VGW_S3_IAM_ACCESS_KEY]
   --s3-iam-secret value                                              s3 IAM secret key [$VGW_S3_IAM_SECRET_KEY]
   --s3-iam-region value                                              s3 IAM region (default: "us-east-1") [$VGW_S3_IAM_REGION]
   --s3-iam-bucket value                                              s3 IAM bucket [$VGW_S3_IAM_BUCKET]
   --s3-iam-endpoint value                                            s3 IAM endpoint [$VGW_S3_IAM_ENDPOINT]
   --s3-iam-noverify                                                  s3 IAM disable ssl verification (default: false) [$VGW_S3_IAM_NO_VERIFY]
   --iam-azure-account value                                          azure IAM storage account name [$VGW_IAM_AZURE_ACCOUNT_NAME]
   --iam-azure-access-key value                                       azure IAM storage account key [$VGW_IAM_AZURE_ACCESS_KEY]
   --iam-azure-sas-token value                                        azure IAM SAS token [$VGW_IAM_AZURE_SAS_TOKEN]
   --iam-azure-url value                                              azure IAM blob service URL, defaults to https://<account>.blob.core.windows.net/ (set it for Azurite or custom endpoints) [$VGW_IAM_AZURE_ENDPOINT]
   --iam-azure-container value                                        azure IAM container, enables the azure blob IAM service [$VGW_IAM_AZURE_CONTAINER]
   --iam-cache-disable                                                disable local iam cache (default: false) [$VGW_IAM_CACHE_DISABLE]
   --iam-cache-ttl value                                              local iam cache entry ttl (seconds) (default: 120) [$VGW_IAM_CACHE_TTL]
   --iam-cache-prune value                                            local iam cache cleanup interval (seconds) (default: 3600) [$VGW_IAM_CACHE_PRUNE]
   --iam-debug                                                        enable IAM debug output (default: false) [$VGW_IAM_DEBUG]
   --health value                                                     health check endpoint path. Health endpoint will be configured on GET http method: GET <health>
                                                                              NOTICE: the path has to be specified with '/'. e.g /health [$VGW_HEALTH]
   --readonly                                                         allow only read operations across all the gateway (default: false) [$VGW_READ_ONLY]
   --disable-strict-bucket-names                                      allow relaxed bucket naming (disables strict validation checks) (default: false) [$VGW_DISABLE_STRICT_BUCKET_NAMES]
   --metrics-service-name value, --msn value                          service name tag for metrics, hostname if blank [$VGW_METRICS_SERVICE_NAME]
   --metrics-statsd-servers value, --mss value                        StatsD server urls comma separated. e.g. 'statsd1.example.com:8125,statsd2.example.com:8125' [$VGW_METRICS_STATSD_SERVERS]
   --metrics-dogstatsd-servers value, --mds value                     DogStatsD server urls comma separated. e.g. '127.0.0.1:8125,dogstats.example.com:8125' [$VGW_METRICS_DOGSTATS_SERVERS]
   --ipa-host value                                                   FreeIPA server url e.g. https://ipa.example.test [$VGW_IPA_HOST]
   --ipa-vault-name value                                             A name of the user vault containing their secret [$VGW_IPA_VAULT_NAME]
   --ipa-user value                                                   Username used to connect to FreeIPA (requires permissions to read user vault contents) [$VGW_IPA_USER]
   --ipa-password value                                               Password of the user used to connect to FreeIPA [$VGW_IPA_PASSWORD]
   --ipa-insecure                                                     Disable verify TLS certificate of FreeIPA server (default: false) [$VGW_IPA_INSECURE]
   --iam-standalone-endpoint value                                    standalone IAM service private-endpoint address: a unix socket path, or <host>:<port> when mTLS (--iam-standalone-client-cert/-key/--iam-standalone-server-ca) is also configured [$VGW_IAM_STANDALONE_ENDPOINT]
   --iam-standalone-access value                                      access key this gateway signs its own calls to the standalone IAM service with (must be set together with --iam-standalone-secret; both default to --access/--secret root) [$VGW_IAM_STANDALONE_ACCESS]
   --iam-standalone-secret value                                      secret key this gateway signs its own calls to the standalone IAM service with (must be set together with --iam-standalone-access; both default to --access/--secret root) [$VGW_IAM_STANDALONE_SECRET]
   --iam-standalone-client-cert value                                 client TLS certificate this gateway presents to the standalone IAM service (required for a non-unix-socket --iam-standalone-endpoint) [$VGW_IAM_STANDALONE_CLIENT_CERT]
   --iam-standalone-client-cert-key value                             private key for --iam-standalone-client-cert [$VGW_IAM_STANDALONE_CLIENT_CERT_KEY]
   --iam-standalone-server-ca value                                   PEM-encoded CA bundle used to verify the standalone IAM service's server certificate (required for a non-unix-socket --iam-standalone-endpoint) [$VGW_IAM_STANDALONE_SERVER_CA]
   --iam-standalone-default-uid value                                 POSIX uid assigned to every account resolved through the standalone IAM backend (it has no per-user POSIX identity of its own) (default: 0) [$VGW_IAM_STANDALONE_DEFAULT_UID]
   --iam-standalone-default-gid value                                 POSIX gid assigned to every account resolved through the standalone IAM backend (default: 0) [$VGW_IAM_STANDALONE_DEFAULT_GID]
   --iam-standalone-default-project-id value                          project id assigned to every account resolved through the standalone IAM backend (default: 0) [$VGW_IAM_STANDALONE_DEFAULT_PROJECT_ID]
   --iam-standalone-policy-cache-ttl value                            how long the standalone IAM backend reuses an identity-policy decision, and so how long a policy change can take to apply (seconds, 0 disables; --iam-cache-disable also disables it) (default: 5) [$VGW_IAM_STANDALONE_POLICY_CACHE_TTL]
   --mp-max-parts value                                               maximum number of parts allowed in a multipart upload (default: 10000) [$VGW_MP_MAX_PARTS]
   --copy-object-threshold value                                      maximum allowed source object size in bytes for CopyObject; objects larger than this are rejected (default: 5368709120) [$VGW_COPY_OBJECT_THRESHOLD]
   --socket-perm value                                                file permissions for file-backed UNIX domain sockets (octal, e.g. '0660'); ignored for TCP/IP and abstract namespace sockets [$VGW_SOCKET_PERM]
   --help, -h                                                         show help

COPYRIGHT:
   Copyright (c) 2023-2026 Versity Software