# virtiofsd instance configuration.
#
# Copy this file to /etc/virtiofsd/<instance>.conf.  Both the systemd unit and
# the OpenRC service read it, so use simple shell-style KEY=value assignments.
# Quote a value when it contains spaces, especially EXTRA_ARGS.
#
# SHARED_DIR is required.  It is the host directory exported to the guest.
# Do not expose more of the host filesystem than the workload needs.
SHARED_DIR=/var/www/example

# Cache policy: auto, always, metadata, or never.
#
# auto     Balanced default.  Use it when the access pattern is not yet known.
# always   Highest throughput when the guest has exclusive control of the tree.
#          Host-side changes may not be visible immediately in the guest.
# metadata Cache metadata but not file contents.  Useful for metadata-heavy
#          trees when full content caching is not appropriate.
# never    Prioritise host/guest coherence over caching performance.  Use this
#          when another host process can modify the exported directory.
CACHE=auto

# Inode file-handle mode: never, prefer, or mandatory.
# prefer is the portable default: it falls back to O_PATH file descriptors when
# file handles are unsupported.  mandatory reduces descriptor pressure but
# requires filesystem support and the CAP_DAC_READ_SEARCH capability.
INODE_HANDLES=prefer

# Sandbox mode: namespace, chroot, or none.
# namespace is the recommended default.  chroot is useful when a container
# runtime already provides namespaces.  Do not use none for untrusted guests.
SANDBOX=namespace

# Extra virtiofsd options, separated by spaces.  Leave this empty unless the
# workload needs a specific virtiofsd feature.
# --posix-acl=auto and --security-label=auto enable xattr support implicitly.
# The service already supplies the socket, shared directory, cache policy,
# sandbox mode, inode-handle mode, and --announce-submounts.
EXTRA_ARGS=

# -----------------------------------------------------------------------------
# Workload profiles
# -----------------------------------------------------------------------------
# Keep one profile per instance file.  Uncomment and adapt a profile below
# instead of mixing settings from multiple profiles.  Benchmark representative
# guest workloads before treating a profile as a production baseline.

# Web application or static site (guest is the only writer)
# Good for a document root that is served and updated only inside the VM.
# Restart virtiofsd after host-side deployments so cached data is invalidated.
# SHARED_DIR=/srv/virtiofs/web
# CACHE=always
# INODE_HANDLES=prefer
# SANDBOX=namespace
# EXTRA_ARGS="--posix-acl=auto --thread-pool-size=8"

# Web application with host-driven deployments
# Use this instead of the previous profile when deployment tools on the host
# update the document root while the VM is running.  It trades cache hits for
# predictable visibility of those external changes.
# SHARED_DIR=/srv/virtiofs/web
# CACHE=never
# INODE_HANDLES=prefer
# SANDBOX=namespace
# EXTRA_ARGS="--posix-acl=auto --thread-pool-size=8"

# Database data directory (PostgreSQL, MariaDB, etc.)
# A database must have exclusive write ownership of its data files: never let
# the host or another guest modify them behind the database server's back.
# This coherent profile honours O_DIRECT requests, avoids content caching, and
# permits guest applications to use memory-mapped data files.
# --allow-mmap can help mmap-heavy workloads, but only when the database is the
# exclusive user of this directory; benchmark it with the real database load.
# Change mandatory to prefer if the backing filesystem lacks file-handle support
# or virtiofsd cannot retain CAP_DAC_READ_SEARCH.
# SHARED_DIR=/srv/virtiofs/postgresql
# CACHE=never
# INODE_HANDLES=mandatory
# SANDBOX=namespace
# EXTRA_ARGS="--allow-direct-io --allow-mmap --thread-pool-size=8 --rlimit-nofile=262144"

# Maildir mail store (many small files and directory operations)
# metadata caching is a middle ground for IMAP/SMTP workloads.  Choose never
# instead if host-side scanners, backup jobs, or another guest alter mailboxes
# while the mail server is online.
# SHARED_DIR=/srv/virtiofs/mail
# CACHE=metadata
# INODE_HANDLES=prefer
# SANDBOX=namespace
# EXTRA_ARGS="--posix-acl=auto --thread-pool-size=8"

# Read-only assets, packages, or reference data
# This gives guests fast reads while preventing writes through virtiofsd.  The
# host can still update the directory; restart the daemon after an update.
# SHARED_DIR=/srv/virtiofs/assets
# CACHE=always
# INODE_HANDLES=prefer
# SANDBOX=namespace
# EXTRA_ARGS="--readonly --thread-pool-size=4"

# Build cache or temporary workspace (guest is the only writer)
# Writeback can improve write-heavy workloads, but enable it only when no other
# host or guest accesses the tree.  It is not a substitute for application
# fsync()/durability guarantees.
# SHARED_DIR=/srv/virtiofs/build
# CACHE=always
# INODE_HANDLES=prefer
# SANDBOX=namespace
# EXTRA_ARGS="--writeback --thread-pool-size=8"

# For CACHE=metadata or CACHE=never, --allow-mmap lets guest applications use
# mmap(2), but only enable it when the guest has exclusive access to the tree.
# Do not add it to directories shared with host deployment, backup, or scanner
# processes.  It only helps applications that actually use memory-mapped I/O.
# Add --xattr only when an application explicitly needs extended attributes;
# do not add it separately when using --posix-acl=auto or --security-label=auto.