Configuration File Reference

Name of the agent - always “velociraptor”

The release version on GitHub.

The commit at which this binary was built. This is more accurate than the version for reporting issues etc.

The time the binary was built.

The URL to the Github Action CI job that built this binary. Not all release binaries are built on the Github CI due to signing requirements.

The version of the Go compiler that built this binary

The time the client was installed (as written in the writeback file).

The operating system this binary is running under.

When using websockets the server will ping the client every this many seconds.

A URL to a proxy that will be used to connect to the server. Some environments have egress filtering requiring Velociraptor to use a proxy to be able to reach the server. NOTE: We do not support PAC based proxy configurations or Windows domain authentication - you might need to add an allow rule to the proxy config to allow the Velociraptor server URL without authentication.

The Internal Velociraptor CA certificate used to verify the server certificates. Do not change this! This will be generated by the config wizard and can not be replaced. It is only used internally.

This is a shared secret between servers and clients. The server will refuse to communicate with clients having the wrong nonce. The nonce is used to group clients into Org Groups - so clients from different orgs have different nonce.

The following are the locations to write the writeback file - this file is used to keep client state. In the default configuration, writeback files persist across uninstall/reinstall cycles to keep the client id consistent. If you don’t want this you can change the location of the writeback to be inside the tempdir_windows directory (it will be removed on uninstall).

On Windows, if the writeback path starts with HKLM\ the path will be interpreted as a registry key that will be used to store the writeback instead of files on disk.

If this value is specified, Velociraptor will create a level 2 writeback file. This second file is used as a backup and to write more frequently updated content. This scheme should reduce the likelihood that the file is corrupted to the point that the client id is lost.

This is the directory Velociraptor will use for temporary files. If not specified or not writable, Velociraptor will use the $TMP or $TEMP env variable.

Number of seconds to wait before polling. Typically Velociraptor connections are persistent but will force a re-connection every max_poll seconds to refresh the connection. NOTE that typically Velociraptor reuses TCP connections so this only applies to the HTTP transactions, i.e. The TCP connections are always up.

Standard deviation between polls adds randomness to the poll period. This ensures that clients are not synchronized to even up the load on the server.

If this is set, the nanny will exit if we are not able to send messages to the server within this many seconds. NOTE - even a failed connection will reset the counter, the nanny will only fire if the client has failed in some way - e.g. the communicator is stopped for some reason

If this is set, prevent arbitrary code execution on clients. NOTE: This will vastly reduce the capabilities of the client.

The default max time to wait before we send partial VQL results. This setting is used to ensure we don’t send too many small requests by batching the rows into time batches.

Maximum number of concurrent queries the client will allow (default 2). This ensures we do not overwhelm the client by scheduling too many concurrent queries. NOTE: Queries marked as URGENT will skip this control and run anyway.

If set the client will hard exit when it uses this much memory (in bytes). This is a safety feature to prevent runaway process - ensure this is not set too low.

Clients will send a Server.Internal.ClientInfo message to the server every this many seconds. This helps to keep the server info up to date about each client. This should not be sent too frequently. The default is 1 day (86400 seconds).

When a collection starts on the client, the client writes a checkpoint file so it can detect when it crashed previously and restarted. If this option is set we disable client checkpoints and so we can not report to the server when the client crashes while collecting an artifact.

If this setting is true, Velociraptor will expect the server to use self signed TLS certificates. The client will verify the TLS connection by checking that the server certificate is signed by the Velociraptor internal CA. With this setting it is possible to use an IP address for the server URL (not recommended though)

Do not change this!

The maximum size of the POST request the client will send to the server. Some proxy servers limit the size of POST messages.

Maximum timeout for connection retry - the length of time we try a connection before restarting it (default 5 min).

Disable client/server compression. Typically no need to change this.

The client normally does not write any logs on the endpoint. However this makes it hard to debug any issues so you can choose to have the client write its logs in a file on the endpoint. The file will be written in an encrypted form which can only be decrypted by the Generic.Client.LocalLogsRetrieve artifact. Path relative to the relevant tmpdir above where client side logs are kept. These logs are encrypted client side and need to be decrypted on the server to read.

On Windows, the client usually runs as a service. If a crash occurs while Velociraptor is running as a Windows service the traceback of the error is printed to Stderr, however a Windows service discards these messages. This means that if Velociraptor crashes we lose the panic backtrace which is useful for debugging why it crashed. This setting allows us to specify a path to a log file on the client where Velociraptor will write stdout and stderr in the event of a crash. This feature is currently not implemented for non-Windows platforms where this setting will have no effect.

Setting this will write clear text network traces to this file. This is used for debugging network communications in complex scenarios (e.g. in the presence of proxies etc). Do not leave this configured in production! This setting will also disable TLS verification for the server name so it will be possible to MITM the client->server connection. NOTE: Velociraptor has 2 layers of encryption - this setting bypasses the outer TLS layer to expose the underlying HTTP communications. Client->server communication still remain encrypted however.

By default when running on a low resource machine we cap the CPU use to 50%. This allows to change that - needs to be between 0 and 100 (100 disables throttling).

We determine we are running on a low resource machine if the system has less than 2 cores. This allows you to increase the threshold. Set to a large number to disable.

If greater than 0 we install a local DNS cache. This is usually not needed as most operating systems already have local DNS caching resolvers. This DNS cache will be refreshed periodically from upstream. Note that the ttl of the record is currently ignored and we refresh according to this setting. This setting takes effect both on the client and on the server.

This is the hostname used to connect to - it is used here to copy into new api client configuration files to assist gRPC API connections (e.g. pyvelociraptor).

Interface to bind to - by default only bind to 127.0.0.1 but will need to be exposed on 0.0.0.0 for external pyvelociraptor clients to connect.

The port to listen on.

Usually these do not need to be changed.

Do not change this. It is the common name of the certificate that will be trusted to be from the GUI. ACL checks will be disabled for all connections from this name.

Allows the GUI to start with no encryption - WARNING This only makes sense if you have TLS proxy in front. In fact the GUI will not work without a TLS proxy because the CSRF cookie is still set to secure only.

You can serve Velociraptor at a sub path of the server. All URLs will then be formed below the base path.

The public URL of this server. Change this if you are proxying the GUI using a different URL.

Header defined by the proxy containing the remote address. This header will be used in the allowed_cidr matching if specified. NOTE: Only use this if you do have a reverse proxy in front of the server. Otherwise an attacker can simply send this header to pretend to come from any IP address. If this setting is specified we take the src address from the header, otherwise from the remote IP address. Default is not set.

Bind the GUI to this port. By default: For self signed SSL the GUI will be bound to the localhost only! For Let’s Encrypt deployments the GUI will be bound on 0.0.0.0 making it accessible from anywhere. NOTE: The only valid settings here are 0.0.0.0 for external access and 127.0.0.1 for localhost - Do not specify any other address unless you know what you are doing!

Bind port for the GUI. When using Let’s Encrypt the GUI is bound to port 443 and this setting is ignored because Let’s Encrypt only supports port 443.

The internal certificate for gRPC connections between the gateway and the API server. DO NOT Change this!

CA private key - the public certificate is in Client.ca_certificate

Serve the Frontend from this base path instead of “/”

This allows the frontends to listen on plain HTTP - It is useful if you have SSL offloading (e.g. nginx). This is not configured by the wizard - you will need to manually configure it. You better know what you are doing here!

Enabling this requires the clients to present a valid certificate (signed by one of the Root CAs listed in Client.Crypto.root_certs or the Velociraptor built in CA itself). NOTE: If you use configurations that place the Frontend and the GUI on the same port then you MUST use the ClientCertificate authenticator. See further discussions at Client.Crypto.client_certificate.

If this setting is enabled it becomes more difficult to troubleshoot the server since a simple curl command will be rejected. To test connectivity with the server you should instead provide client cert and key files:

curl -kv https://localhost:8000/server.pem –cert client.pem –key key.pem

A proxy setting to use - Velociraptor needs to connect to download tools. This setting will force it to go out over this proxy. NOTE- If you don’t want to allow outbound connections, just set this to an non-existent setting (e.g. http://127.0.0.1:3128).

SECURITY: This proxy setting and the proxy_config below control ALL server-initiated outbound HTTP connections, including tool materialization and VQL’s http_client() plugin. Without a proxy or with a permissive proxy, any user with admin-equivalent permissions can make the server fetch arbitrary URLs, including internal RFC 1918 addresses and cloud endpoints. Set a restrictive proxy or configure proxy_url_regexp to limit outbound destinations

Velociraptor can attempt to obfuscate artifact names when compiling them into raw VQL. If this is set to false this obfuscation is removed.

The publicly accessible hostname of the frontend.

Which interface to bind to. Usually the frontend is bound to 0.0.0.0 to allow all clients to connect from anywhere.

These are used to secure the client/server communications - Even when using external TLS certificates! This certificate must be signed by the Velociraptor root CA in all cases (tls_certificate_filename for that). If using an external TLS configuration this layer of encryption happens in addition to the external TLS certificates.

If you want to use your own certificates for TLS as an alternative to Autocert, then you can set those here. These certificates will be used for TLS on both the frontend and GUI. NOTE: We expect these to be proper certificates - i.e. NOT self signed. If you want to use certificates issued by another CA you will also need to add that CA cert to the Client.Crypto.root_certs field.

Be sure to set Client.use_self_signed_ssl=false when you set this.

Header defined by the proxy containing the remote address. If this is not set we use the remote IP address from the TCP connection. This setting is needed if you have a reverse proxy in front of the server.

The user that the frontend should run as. If set we refuse to run as a different user. This is normally set by the Ubuntu deb package as it is running as a low privilege user called “velociraptor”. This setting is important as it stops users from running velociraptor as root with sudo - doing this will break the velociraptor datastore when it creates files only readable by root.

Number of gRPC connections in the pool to use to connect to the API server.

Load artifacts from this directory at startup

A regular expression that if matches any log messages from the client’s query represent a failure of the collection. Marking the collection as failed can highlight potential problems with the VQL so this regex tries to detect common issues (e.g. Symbol not found) to draw attention to failures.

The data store implementation to use. This is usually set to FileBaseDataStore.

The directory under which we store small files.

Larger result sets and uploads are stored in the filestore_directory. This is usually the same as the location setting but it can be different to keep larger slower storage options away from smaller and faster data.

How long before a write is forced from the pool for delayed writes

Maximum amount of data cached in memory before we force it to be flushed to disk. Default 100mb

When using a master/minion setup it is necessary to have the Master and Minion nodes use different filesystem implementations. These more specific parameters can control datastore implementations on the master and minion separately.

Cap directories to this size after reporting error - this should not happen normally but may happen if the deployment has been very active or due to a bug!

Set to the min required disk space. When we fall below this available disk space, we refuse to write files. This avoids the possibility of writing corrupted files. Default is 50mb. Set to -1 to disable disk space monitoring.

How often to check the disk space (default 10 sec)

The following apply to the MemcacheFileDataStore How long to expire the memcache (default 10 min)

How many mutations to queue up ahead of busy writers. By default 0 means writes will be blocked until they are handed off to a writer thread. Set to -1 to disable asynchronous writes.

The MemcacheFileDataStore separates writers into a writing pool. These set the number of writer threads in that pool. Number of writing threads - increase for high latency filesystems (default 100).

How long to delay writes so they can be combined. This applies for writing result sets - we keep the writes in memory for min_age seconds in order to combine further writes. If another write occurs to the same result sets the TTL is extended and writes are delayed. However, once we reach max_age, a write is forced. The aim is to keep combining separate writes as much as possible into larger writes but at the same time prevent frequently written files from never flushing to disk.

MemcacheFileDataStore will cache small files in memory to improve efficiency. This is the maximum size of the cache. Maximum size of memcache lru (default 10000)

Do not cache large objects in memory - falls back to FileBaseDataStore

The compression mode for collections. This setting allows compressed results to be stored on the server. For performance reasons, the client must compress the data into chunks and the server simply writes the results to storage. This means it is only supported by clients more recent than 0.75.

Allowed settings:

• none: No compression - disable compression in client transmission. Note that for older clients (prior to 0.75), compression is not supported anyway, but this setting will disable compression on new clients as well.

• zlib: Zlib compression enabled on collections. This is the default setting when communicating with newer clients.

The maximum size of stored objects in the datastore. The Datastore is assumed to contain smallish objects which are read and written atomically. This setting places a limit on the size of these objects to maintain efficiency and speed. If you hit this limit it means that you need to rethink your approach. See https:docs.velociraptor.app/knowledge_base/tips/grpc_errors/ The default size is 4Mb.

A directory to write log files in .

If this is set the logs will be separated into different components (e.g. Frontend, GUI, Audit etc). This makes it easier to find the source of the log messages

If you want to forward events to a remote syslog server, fill this server addresss or hostname. If a port is omitted we use port 514.

The protocol to use for remote syslog (default udp).

If set we use this in links etc, otherwise we take a guess based on bind_address and bind_port above.

Normally notebook queries timeout in 10 minutes (can not be changed from within the notebook). This is done to reduce load on the server. If you want to increase notebook timeout you can change this.

By default new cells only list 50 rows if there is no custom cell template. This is to make refreshing the cell quick. Usually users need to edit or the limit clause to see the full result table in the cell. This setting increases the default 50 rows.

When running on a shared server notebook calculations can increases memory use and affect other users. The following settings control notebook calculations to ensure they do not use too much memory. You should set the following in accordance with the VM settings of the server with a small margin of safety. When calculating a new cell we do not start calculation until the process memory is smaller than the low memory mark.

When the process memory exceeds the high water mark, we actively cancel in flight notebook cell calculations to bring memory use down.

Since Version 0.7.1, notebook queries are run in separate worker threads, even on single server configurations. This parameters sets the number of workers available.

Set to -1 to disable local workers. The default is 5 local workers. If you want the master to not perform any notebook computations reduce this to -1 and set Minion.notebook_number_of_local_workers to 5.

Wait this long for a worker to become available before giving up. The default is 10 seconds.

The default priority of notebook processors (Higher priority will receive jobs over lower priority).

When exporting to CSV from the GUI the usual separator is comma (,). This setting allows to change the default to any single character.

By default hunts expire in 7 days but you can change this using this setting.

Default value of max_wait and relevant jitter for new event queries the GUI creates.

If set we actively notify all clients as soon as event table is changed. This causes a lot of load on large deployments so it is off by default. It means that you will need to wait for the client to reconnect before it receives updates to its event table (usually about 5 min). When running velociraptor gui we set this to true in order to get a responsive GUI.

The number of rows to keep in memory during a group by operation. Once this is exceeded we switch to disk mode which is a lot slower but has no memory limitations. Default 30000

How long to cache ACL policies (default 60 sec)

Ignore messages from unauthenticated clients for this long - gives them a chance to enrol first (default 10 sec).

Controls how exports work (creating hunt or collection exports to a zip file). On slow filesystems, increase the number of worker threads to increase parallelism. You can also increase the timeout if the filesystem is too slow to build large hunt zip files within the default 10 minute timeout.

The server maintains an index of all hunts in order to quickly allow the GUI to filter/sort them. This setting controls how often to rebuild the hunt index (default 600 sec). You probably don’t need to change it.

The hunt dispatcher index rebuild is rate limited to reduce load on the server. This sets how fast it should go (in flows per second). You probably do not want to change this.

Total number of cell versions we keep for undo/redo support.

Watch plugin frequency sleep time in seconds: How often watch_syslog() will check for changes (default 3).

Maximum length of the line that will be parsed (16kb)

Period in seconds when to produce a backup. Velociraptor will generate a backup of important metadata about the server. By default this happens daily but you can change it here (set to -1) to disable backups.

The server’s client info manager runs housekeeping tasks periodically to determine if clients need to be notified. This setting controls how often to run the client info’s house keeping thread in seconds (default 60 sec)

Disable unicode usernames. By default Velociraptor allows usernames to consist of any Unicode character for i8n support, however this opens the possibility for Homoglyph attacks. Setting the following to true will restrict usernames to the set a-z and 0-9

How often to refresh the search index (default 5 min). This rebuilds the search index periodically to avoid inconsistencies.

If this is set we do not actively check the status of in-flight collections. This is a new feature to 0.73 and may need to be disabled in some large deployments due to additional overheads.

Normally internal event artifacts are not written to disk but passed internally. For debugging it is useful to have a written record though. Enabling this will also write them to disk. Probably only useful for debugging.

Defaults for client communication limits. Decrease those if your clients are behind a proxy that only accepts very small POST messages. If not set we use client defaults.

Maximum default value for log messages sent by the client for each flow. Once this is reached, the client stops sending log messages in the current collection.

Used to override Defaults.notebook_number_of_local_workers

Used to override Defaults.notebook_worker_priority. By default minion workers have higher priority than the master node allowing minions to take over notebook calculations most of he time.

Default expiry of certificate issuance (default 365 days). This will apply for e.g. rotating certificates or issuing an api cert.

Normally the inventory service attempts to download tools in its own but if this is set, we prevent any external access.

The Data Encryptions Key to use for protecting the secrets in storage. This can take a number of forms:

1. If it starts with env://<VAR> the secret will be taken from an Environment variable.
2. If empty the secret is taken from obfuscation_nonce (which by default is the hash of the private key).

In future further methods may be implemented (e.g. EKMS).

See the following for more information http://docs.velociraptor.app/docs/deployment/security/#protecting-stored-secrets

This controls VQL plugins that may accept secrets as well full parameters. If this flag is set, those plugins will refuse to accept direct parameters, instead only accepting a secret name. This allows the admin to control exactly how these plugins work without disabling them completely.