Audit Service Configuration

Introduction

The audit service logs all events of the system as an audit log. With audit logs, you are able to prove compliance with corporate and legal guidelines as well as enable reporting and auditing of operations.

  • The audit service does not start automatically and must be started manually. For more details see the Start Infinite Scale section.

  • The reason for excluding the audit service from autostart is, that you only need it when you plan to implement auditing.

Supported log formats are json or a minimal human-readable format. The audit service takes note of actions conducted by users and administrators.

Example minimal format
file_delete)
   user 'user_id' trashed file 'item_id'
file_trash_delete)
   user 'user_id' removed file 'item_id' from trashbin
Example json
{"RemoteAddr":"","User":"user_id","URL":"","Method":"","UserAgent":"","Time":"","App":"admin_audit","Message":"user 'user_id' trashed file 'item_id'","Action":"file_delete","CLI":false,"Level":1,"Path":"path","Owner":"user_id","FileID":"item_id"}
{"RemoteAddr":"","User":"user_id","URL":"","Method":"","UserAgent":"","Time":"","App":"admin_audit","Message":"user 'user_id' removed file 'item_id' from trashbin","Action":"file_trash_delete","CLI":false,"Level":1,"Path":"path","Owner":"user_id","FileID":"item_id"}

The audit service is not started automatically when running as single binary started via ocis server or when running as docker container and must be started and stopped manually on demand.

Per default, it will be logged to standard out, but can also be configured to write into a file. Note that when a file output is used, it is not part of the standard log file but a separate one.

The audit service logs:

  • File system operations
    (create/delete/move; including actions on the trash bin and versioning)

  • User management operations
    (creation/deletion of users)

  • Sharing operations
    (user/group sharing, sharing via link, changing permissions, calls to sharing API from clients)

Event Bus Configuration

The Infinite Scale event bus can be configured by a set of environment variables.

  • If you are using a binary installation as described in Minimal Bare Metal Deployment or Bare Metal with systemd, the address of the event bus OCIS_EVENTS_ENDPOINT is predefined as localhost address without the need for further configuration, but changeable on demand.

  • In case of an orchestrated installation like with Docker or Kubernetes, the event bus must be an external service for scalability like a Redis Sentinel cluster or a key-value-store NATS JetStream. Both named stores are supported and also used in Caching and Persistence. The store used is not part of the Infinite Scale installation and must be separately provided and configured.

  • Note that from a configuration point of view, caching and persistence are independent of the event bus configuration.

Note that for each global environment variable, a service-based one might be available additionally. For precedences see Environment Variable Notes. Check the configuration section below.

Without the aim of completeness, see the list of environment variables to configure the event bus:

Envvar Description

OCIS_EVENTS_ENDPOINT

The address of the event system.

OCIS_EVENTS_CLUSTER

The clusterID of the event system. Mandatory when using NATS as event system.

OCIS_EVENTS_ENABLE_TLS

Enable TLS for the connection to the events broker.

OCIS_INSECURE

Whether to verify the server TLS certificates.

OCIS_EVENTS_AUTH_USERNAME

The username to authenticate with the events broker.

OCIS_EVENTS_AUTH_PASSWORD

The password to authenticate with the events broker.

Configuration

Environment Variables

The audit service is configured via the following environment variables. Read the Environment Variable Types documentation for important details. Column IV shows with which release the environment variable has been introduced.

  • master + Rolling 6.6.1

Environment variables for the audit service
Name IV Type Default Value Description

OCIS_TRACING_ENABLED
AUDIT_TRACING_ENABLED

pre5.0

bool

false

Activates tracing.

OCIS_TRACING_TYPE
AUDIT_TRACING_TYPE

pre5.0

string

The type of tracing. Defaults to '', which is the same as 'jaeger'. Allowed tracing types are 'jaeger' and '' as of now.

OCIS_TRACING_ENDPOINT
AUDIT_TRACING_ENDPOINT

pre5.0

string

The endpoint of the tracing agent.

OCIS_TRACING_COLLECTOR
AUDIT_TRACING_COLLECTOR

pre5.0

string

The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset.

OCIS_LOG_LEVEL
AUDIT_LOG_LEVEL

pre5.0

string

The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.

OCIS_LOG_PRETTY
AUDIT_LOG_PRETTY

pre5.0

bool

false

Activates pretty log output.

OCIS_LOG_COLOR
AUDIT_LOG_COLOR

pre5.0

bool

false

Activates colorized log output.

OCIS_LOG_FILE
AUDIT_LOG_FILE

pre5.0

string

The path to the log file. Activates logging to this file if set.

AUDIT_DEBUG_ADDR

pre5.0

string

127.0.0.1:9229

Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.

AUDIT_DEBUG_TOKEN

pre5.0

string

Token to secure the metrics endpoint.

AUDIT_DEBUG_PPROF

pre5.0

bool

false

Enables pprof, which can be used for profiling.

AUDIT_DEBUG_ZPAGES

pre5.0

bool

false

Enables zpages, which can be used for collecting and viewing in-memory traces.

OCIS_EVENTS_ENDPOINT
AUDIT_EVENTS_ENDPOINT

pre5.0

string

127.0.0.1:9233

The address of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture.

OCIS_EVENTS_CLUSTER
AUDIT_EVENTS_CLUSTER

pre5.0

string

ocis-cluster

The clusterID of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture. Mandatory when using NATS as event system.

OCIS_INSECURE
AUDIT_EVENTS_TLS_INSECURE

pre5.0

bool

false

Whether to verify the server TLS certificates.

OCIS_EVENTS_TLS_ROOT_CA_CERTIFICATE
AUDIT_EVENTS_TLS_ROOT_CA_CERTIFICATE

pre5.0

string

The root CA certificate used to validate the server’s TLS certificate. If provided AUDIT_EVENTS_TLS_INSECURE will be seen as false.

OCIS_EVENTS_ENABLE_TLS
AUDIT_EVENTS_ENABLE_TLS

pre5.0

bool

false

Enable TLS for the connection to the events broker. The events broker is the ocis service which receives and delivers events between the services.

OCIS_EVENTS_AUTH_USERNAME
AUDIT_EVENTS_AUTH_USERNAME

5.0

string

The username to authenticate with the events broker. The events broker is the ocis service which receives and delivers events between the services.

OCIS_EVENTS_AUTH_PASSWORD
AUDIT_EVENTS_AUTH_PASSWORD

5.0

string

The password to authenticate with the events broker. The events broker is the ocis service which receives and delivers events between the services.

AUDIT_LOG_TO_CONSOLE

pre5.0

bool

true

Logs to stdout if set to 'true'. Independent of the LOG_TO_FILE option.

AUDIT_LOG_TO_FILE

pre5.0

bool

false

Logs to file if set to 'true'. Independent of the LOG_TO_CONSOLE option.

AUDIT_FILEPATH

pre5.0

string

Filepath of the logfile. Mandatory if LOG_TO_FILE is set to 'true'.

AUDIT_FORMAT

pre5.0

string

json

Log format. Supported values are '' (empty) and 'json'. Using 'json' is advised, '' (empty) renders the 'minimal' format. See the text description for more details.

YAML Example

  • master + Rolling 6.6.1

# Autogenerated
# Filename: audit-config-example.yaml

tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9229
  token: ""
  pprof: false
  zpages: false
events:
  endpoint: 127.0.0.1:9233
  cluster: ocis-cluster
  tls_insecure: false
  tls_root_ca_certificate: ""
  enable_tls: false
  username: ""
  password: ""
auditlog:
  log_to_console: true
  log_to_file: false
  filepath: ""
  format: json