Environment variables

Introduction

Generally, AIStore (AIS) configuration comprises several sources:

1. cluster (a.k.a. global) and node (or, local) configurations, the latter further “splitting” into local config per se and local overrides of the inherited cluster config;
2. aisnode command line;
3. environment variables (this document);
4. finally, assorted low-level constants (also referred to as “hardcoded defaults”) that almost never have to change.

This enumeration does not include buckets (and their respective configurations). In AIS, buckets inherit a part of the cluster config that can be further changed on a per-bucket basis - either at creation time or at any later time, etc.

In effect, cluster configuration contains cluster-wide defaults for all AIS buckets, current and future.

For additional references, please see the last section in this document. The rest of it, though, describes only and exclusively environment variables - item 3 above.

Rules

First though, two common rules that, in fact, apply across the board:

• in AIS, all environment settings are optional
• if specified, environment variable will always override:
  • the corresponding default constant (if exists), and/or
  • persistent configuration (again, if the latter exists).

For example:

• in AIS cluster, each node has an ID, which is persistent, replicated and unique; at node startup its ID can be overridden via AIS_DAEMON_ID environment (see below);
• environment AIS_READ_HEADER_TIMEOUT, if specified, will be used instead of the apc.ReadHeaderTimeout constant in the code;
• AIS_USE_HTTPS takes precedence over net.http.use_https value from the cluster configuration,

and so on.

Table of Contents

The remainder of this text groups AIS environment variables by their respective usages, and is structured as follows:

• Build Tags
• Primary
• Network
• Node
• HTTPS
• Local Playground
• Kubernetes
• Package: backend
  • AIS as S3 storage
• Package: stats
• Package: memsys
• Package: transport

separately, there’s authentication server config:

• AuthN

and finally:

• References

Build Tags

Different AIS builds may (or may not) require different environment vars. For complete list of supported build tags, please see conditional linkage. Here’s a very brief and non-exhaustive intro:

1
# 1) no build tags, no debug
2
MODE="" make node
3
4
# 2) no build tags, debug
5
MODE="debug" make node
6
7
# 3) cloud backends, no debug
8
AIS_BACKEND_PROVIDERS="aws azure gcp" MODE="" make node
9
10
# 4) cloud backends, debug
11
AIS_BACKEND_PROVIDERS="aws azure gcp" MODE="debug" make node
12
13
# 5) cloud backends, debug
14
TAGS="aws azure gcp debug" make node
15
16
# 6) debug, nethttp (note that fasthttp is used by default)
17
TAGS="nethttp debug" make node

Primary

Background: in a running AIS cluster, at any point in time there’s a single primary gateway that may also be administratively selected, elected, reelected. Hence, two related variables:

$
$ AIS_PRIMARY_EP=https://ais-proxy-0.svc.cluster.local:51082
$
# or (same):
$
$ AIS_PRIMARY_EP=ais-proxy-0.svc.cluster.local:51082

Network

Node

See also:

• three logical networks

HTTPS

At first it may sound slightly confusing, but HTTP-wise AIS is both a client and a server.

All nodes in a cluster talk to each other using HTTP (or HTTPS) - the fact that inevitably implies a certain client-side configuration (and configurability).

In particular, AIS server-side HTTPS environment includes:

E.g., for local playground, typical usage starts from running export AIS_USE_HTTPS=true followed by one of the usual make deploy combinations.

In addition, all embedded (intra-cluster) clients in a cluster utilize the following environment:

Further references

• Generating self-signed certificates
• Deploying: 4 targets, 1 gateway, 6 mountpaths, AWS backend
• Accessing HTTPS-based cluster
• Testing with self-signed certificates
• Observability: TLS related alerts
• Updating and reloading X.509 certificates
• Switching cluster between HTTP and HTTPS

Local Playground

This group of environment variables is used exclusively by development scripts and integration tests.

See also:

• scripts/clean_deploy.sh
• wait-for-cluster
• api/env package readme

Kubernetes

Kubernetes POD name is also reported via ais show cluster CLI - when it is a Kubernetes deployment, e.g.:

1
$ ais show cluster t[fXbarEnn]
2
TARGET         MEM USED(%)   MEM AVAIL     CAP USED(%)   CAP AVAIL     LOAD AVERAGE    REBALANCE   UPTIME        K8s POD         STATUS  VERSION        BUILD TIME
3
t[fXbarEnn]    3.08%         367.66GiB     51%           8.414TiB      [0.9 1.1 1.3]   -           1852h19m40s   ais-target-26   online  3.20.92bc0c1   2023-09-18T19:12:52+0000

See related:

• AIS K8s Operator: environment variables

AWS S3

NOTE: for the most recent updates, please refer to the source.

Package: backend

AIS natively supports 3 (three) Cloud storages.

The corresponding environment “belongs” to the internal backend package and includes:

Notice in the table above that the variables S3_ENDPOINT and AWS_PROFILE are designated as global: cluster-wide.

The implication: it is possible to override one or both of them on a per-bucket basis:

• configuring buckets with alternative S3 andpoint and/or credentials

AIS as S3 storage

Environment S3_ENDPOINT is important, and may also be a source of minor confusion. The reason: AIS itself provides S3 compatible interface.

For instance, on the client side you could say something like:

1
export S3_ENDPOINT=https://10.0.4.53:51080/s3

and then run existing S3 applications against an AIS cluster at 10.0.4.53 - with no changes (to the application).

Moreover, configure AIS to handle S3 requests at its ”/” root:

1
$ ais config cluster features S3-API-via-Root

and re-specify S3_ENDPOINT environment to make it looking slightly more conventional:

1
export S3_ENDPOINT=https://10.0.4.53:51080

To recap:

• use S3_ENDPOINT to override the s3.amazonaws.com default;
• specify AWS_PROFILE to use a non-default (named) AWS profile

and separately:

• you could run existing S3 apps (with no changes) against AIS by using S3_ENDPOINT on the client side

See also:

• AIS buckets
• Bucket configuration: AWS profiles
• Using AIS as S3 endpoint

Package: stats

AIStore is a fully compliant Prometheus exporter.

StatsD was deprecated in v3.28 (Spring 2025) and completely removed in v4.0 (September 2025).

Package: memsys

Package: transport

See also: streaming intra-cluster transport.

AuthN

AIStore Authentication Server (AuthN) provides secure access control to AIStore via JSON Web Tokens.

A single AuthN service can support multiple AIS clusters, with no fixed limit.

The following variables can be used to configure deployment scripts and validation of tokens in AIStore:

For configuring the AuthN service and clients, see the AuthN Environment Variables.

When AuthN is disabled (i.e., not used), the respective ais config command will show something like:

1
$ ais config cluster auth
2
PROPERTY                         VALUE
3
auth.signature.key               **********
4
auth.signature.method            hmac
5
auth.required_claims.aud         []
6
auth.oidc.issuer_ca_bundle
7
auth.oidc.allowed_iss            []
8
auth.cluster_key.enabled         false
9
auth.cluster_key.ttl             0s
10
auth.cluster_key.nonce_window    1m
11
auth.cluster_key.rotation_grace  1m
12
auth.enabled                     false ## <<<< disabled

Notice: this command is executed on the AIStore cluster, not AuthN.

See also:

• AIS token validation
• AIS AuthN server
• AIS AuthN server: CLI management

References

• env package README
• system filenames
• cluster configuration
• local playground: cluster and node configuration
• ais config command
• performance tunables
• feature flags