This is an annotated server.config.yaml with complete explanations
for all options currently available.
The values you see are the default values that will be used when the
option is omitted.
This is the version of the Velociraptor binary used to generate
this configuration file. It simply annotates the produced file and
can not be changed. When Velociraptor loads the configuration file,
this field will be updated so for example `velociraptor config
show` will update this to the present version.
The Client block will be copied into the client.config.yaml and it
is expected to be used by clients. It contains no secrets and can
be embedded into clients. The server must also have this block as
it needs to refer to client specific information sometimes.
These are the root CA certs the client will trust. This is
needed when going through a MITM proxy. Certificates are in PEM
format one after the next. Certificates do not have to have the
CA basic constraint!
Clients may connect to servers which use a self-signed certificate.
This list allows to specify a set of certificate thumbprints (SHA256)
which are used to validate TLS server certificates.
Fingerprints can be generated with the OpenSSL command line utility:
openssl s_client -connect www.google.com:443 < /dev/null | openssl x509 -fingerprint -sha256 -noout
Certificate thumbprints may or may not include colon characters. Capitalization
of the hex digits is ignored by Velociraptor. A thumbprint of any of the
forms used below (or combinations thereof) is fine.
Velociraptor supports several ways of verifying TLS certificates. The
certificate_verification_mode specifies which of the three modes is applied.
Currently, three modes are available:
PKI (the default):
verify TLS certs against public CA lists, the list of additional root_certs (see above),
and the built-in CA cert
the same as PKI with the addition that certificates which have a thumbprint that is
present in certificate_thumbprints will be accepted as well
Velociraptor only accepts certificates which have a matching thumbprint in
certificate_thumbprints. All other certificates will be rejected. This mode is
also known as certificate pinning.
A list of one or more URLs the clients will try to connect
to. When all connections fail the client will back off for a
while. Clients will choose one of these at random so it is a good
way of acheiving fault tolerance and load balancing.
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.
Generated by the config wizard!!!
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 (See Writeback section). 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 inside the tempdir_windows directory (it will be
removed on uninstall).
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.
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
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 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)
It is possible to pre-label clients using the configuration
file. The server will add these labels to the clients
automatically upon enrollment. This allows different client
packages to be distributed in the real world and have them
Velociraptor keeps a local buffer file to store query results
while they are being shipped across the network. There are two
types of buffers - an in memory buffer and a local file based
buffer file. When the buffer is exceeded the query is paused so
it is important to have reasonable size available for the buffer
file to prevent queries taking too long (and possibly timing
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.
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
When the Velociraptor server starts for the first time, the
server can create the following initial user with admin level
access. This is designed to automate deployment and allow users
to sign in immediately to the GUI. You can remove these accounts
or change their ACLs/Roles later.
Name of this authenticator to show in the GUI (e.g company
name). Note that you can provide many OIDC authenticators as
part of the multi authenticator so having a name here helps keep
This allows the frontends to listen on plain HTTP - It is useful
if you have SSL offloading (e.g. ngix). This is not configured by
the wizard - you will need to manually configure it. You better
know what you are doing here!
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 dont want to allow outbound connections, just set this to
an non existent setting (e.g. http://127.0.0.1:3128).
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 Frontend.Crypto.root_certs and
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 priv 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
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 maximum number of concurrent client connections we can
process. Concurrency limits helps to ensure the server is not
overloaded serving too many clients at the same time.
Concurrency refers to the actual serving time of a client
(i.e. time taken to read the response and write to the
datastore), not the total number of clients served by
server. Default is number of cores * 2.
This setting controls the size of various LRU caches in the
frontend (e.g. the session key cache, client info cache). This
number should be larger than the number of actual clients or
else the system will see high CPU load from cache misses.
Bandwidth control: Per client and global rates in
bytes/sec. This is useful for low bandwidth deployments where we
want to ensure Velociraptor does not saturate slow links. The
bandwidth limitation caps the total bandwidth used by the server
per client and globally.
Number of seconds before expiring client info cache
entries. Default (0) means do not expire at all. Expiring
client info from cache too frequently can result in a lot more
IO. Default size of this cache is the expected_clients above.
The journal files are used to queue messages between event
generators and event consumers when the consumer is unable to
drain these quickly enough. The setting specifies the maximum
size of the file - when it is exceeded, the file will be
truncated and events will be lost. Default is 1gb
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.
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.
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.
When starting without any command line parameters, this argv array
will be used as if it was typed on the command line. This is a way
to get Velociraptor to automatically execute a function as
startup when used without parameters.
Load these artifact definitions into the binary at startup. NOTE:
These definitions are considered "built-in" which will ensure they
can not be modified at runtime.
The format of these fields is an artifact definition - so the
following description also covers artifact definitions more
Artifacts can specify third party tools to load. Velociraptor
will attempt to fetch these tools when a user wants to collect
this artifact. Velociraptor will push the tool to the endpoint
so the artifact may use it.
Once the tool is added with the above fields, the following
fields are used to keep state on it.
The URL we serve the tool from when we serve locally. If this
is empty we just let the endpoint download its own tool from
the url above.
The name of the cached file on the endpoint. This file will
persist and can be accessed again if this tool is needed in
future. If the file is missing (or has the wrong hash), then it
will be downloaded again.
If the artifact specifies a precondition the client will
evaluate this query before evaluating the main artifact. If the
precondition returns no rows (ie. FALSE) then the artifact will
not be collected. You can use the precondition to protect
incompatible clients from collecting the artifact (usually the
This is used to obfuscate artifact names when sending to the
client. NOTE: This is currently not very robust - i.e. it does not
hide the artifact names very well - you should not name artifacts
in a sensitive way.
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.
When viewing the VFS on a client we create objects in the data
store to facilitate the GUI navigation. If the directory is too
large the GUI performance suffers so we truncate the directory at
this size (default 1000 files).
If these are set we enforce VQL to only have the specified allowed
VQL plugins and functions. This is a way to harden the server by
removing potentially sensitive functionality to allow only
approved VQL plugins to run.