File Hierarchy
Pigsty FHS
The default Pigsty home directory is ~/pigsty. It has this file structure:
~/pigsty Source Tree
app/
- Application template resources
bin/
- Administration scripts such as `node-add`, `pgsql-add`, `vault-add`, and `vault-rm`
conf/
- meta.yml
- … · Other single-node templates
fork/
- Kernel fork templates such as pgsql, mssql, and ivory
ha/
- High-availability topology templates
app/
- Application templates
demo/
- Demonstration templates
build/
- Multi-platform build inventories
files/
victoria/
- Rules and operations scripts
grafana/
- Grafana dashboards
postgres/
- PostgreSQL management scripts
migration/
- Data-migration task definitions
pki/
- Self-signed CA and certificates
roles/
- Ansible role implementations
templates/
- Ansible templates
vagrant/
- Vagrant sandbox definitions
terraform/
- OpenTofu cloud-resource templates (Terraform-compatible)
- configure
- ansible.cfg
- pigsty.yml
- deploy.yml / infra.yml / node.yml / etcd.yml / vault.yml / minio.yml / pgsql.yml / …
- *-rm.yml · Module removal playbooks, such as `pgsql-rm.yml`, `vault-rm.yml`, and `mysql-rm.yml`
Kernel fork templates reside under conf/fork/. See Configuration Templates for the full list.
/infra is a runtime symlink to /data/infra. This directory contains observability data and generated configuration:
CA FHS
Pigsty’s self-signed CA is located in files/pki/ under the Pigsty home directory.
You must keep the CA key file secure: files/pki/ca/ca.key. The ca role generates this key when you run deploy.yml or infra.yml.
pigsty/files/pki · (local_user) 0755
ca · (local_user) 0700/
- ca.key · 0600, keep secret
- ca.crt · 0644, trusted by all nodes
vault · (local_user) 0700, OpenBao unseal key, initialization credentials, backups, and server certificates/
- unseal.key · 0600, 32-byte static unseal key, keep secret
- init.json · 0600, initial root token and recovery material
- backup.token · 0600, snapshot-only backup token
- backup/ · 0700, snapshots collected on the control node
- <vault_instance>.{key,crt} · 0600/0644, OpenBao server certificates
- csr · (local_user) 0755, certificate signing requests/
- misc · (local_user) 0755, miscellaneous and issued certificates/
- etcd · (local_user) 0755, etcd server certificates/
- minio · (local_user) 0755, minio server certificates/
- nginx · (local_user) 0755, Nginx SSL certificates/
- infra · (local_user) 0755, infra client certificates/
- pgsql · (local_user) 0755, pgsql server certificates/
- kafka · (local_user) 0755, Kafka server certificates/
- mysql · (local_user) 0755, MySQL server certificates/
Pigsty installs these certificate files on managed nodes:
All infra nodes have these certificates:
If the admin node fails, files/pki and pigsty.yml should be available on the backup admin node. Use rsync to copy them:
INFRA FHS
The infra role creates infra_data (default: /data/infra) and creates a symlink /infra -> /data/infra.
The permissions for /data/infra are root:infra 0771. Subdirectories default to *:infra 0750, unless overridden:
/infra → /data/infra · root:infra 0771
pgadmin · 5050:5050 0700/
- servers.json · 5050:5050 0600, pgAdmin server list
- pgpass · 5050:5050 0600, pgAdmin connection passwords
- alertmgr · prometheus:infra 0700/
conf · root:infra 0750/
- patronictl.yml · root:admin 0640
- tmp · root:infra 0750/
hosts · dnsmasq:dnsmasq 0755, DNS records/
- default · root:root 0644
datasources · root:infra 0750/
- *.json · 0600, generated by register
- dashboards · root:infra 0750/
- metrics · victoria:infra 0750/
- logs · victoria:infra 0750/
- traces · victoria:infra 0750/
bin · victoria:infra 0750/
- check · root:infra 0755
- new · root:infra 0755
- reload · root:infra 0755
- status · root:infra 0755
rules · victoria:infra 0750/
- agent.yml · victoria:infra 0644
- infra.yml · victoria:infra 0644
- node.yml · victoria:infra 0644
- pgsql.yml · victoria:infra 0644
- redis.yml · victoria:infra 0644
- etcd.yml · victoria:infra 0644
- vault.yml · victoria:infra 0644
- minio.yml · victoria:infra 0644
- kafka.yml · victoria:infra 0644
- mysql.yml · victoria:infra 0644
targets · victoria:infra 0750/
- infra · infra component targets, files 0640/
- node · node targets, files 0640/
- ping · ping targets, files 0640/
- etcd · etcd targets, files 0640/
- vault · OpenBao targets, files 0640/
- pgsql · pgsql targets, files 0640/
- pgrds · pgrds targets, files 0640/
- redis · redis targets, files 0640/
- minio · minio targets, files 0640/
- juice · JuiceFS targets, files 0640/
- mysql · MySQL targets, files 0640/
- kafka · Kafka targets, files 0640/
- docker · Docker targets, files 0640/
- patroni · Patroni SSL targets, files 0640/
- prometheus.yml · victoria:infra 0644
This structure is created by: roles/infra/tasks/dir.yml, roles/infra/tasks/victoria.yml, roles/infra/tasks/register.yml, roles/infra/tasks/dns.yml, and roles/infra/tasks/env.yml.
Remote PostgreSQL / RDS exporters deployed on INFRA through pgsql-monitor.yml (roles/pg_exporters) also create /etc/pg_exporter/ (prometheus:infra 0755) with per-unit <unit>.yml files (0644). Only remote monitoring uses this directory; local exporters on PGSQL nodes use /etc/pg_exporter.yml directly.
Certbot integration also writes /etc/letsencrypt/renewal-hooks/deploy/10-reload-nginx (0755) to reload Nginx after renewal.
NODE FHS
node_data specifies the node data directory. The default is /data, with owner root:root and mode 0755.
Default module data and backup directories are organized under /data:
/data · root:root 0755
- postgres · postgres:postgres 0700, default pg_fs_main/
- backups · postgres:postgres 0700, default pg_fs_backup; MySQL backups default to /data/backups/mysql/
- vault · openbao:openbao 0700, default vault_data; raft/ 0700 and backup/ root:root 0700/
- redis · redis:redis 0700, shared by multiple instances/
- minio · minio:minio 0750, single-node single-drive mode/
- etcd · etcd:etcd 0700, etcd_data/
- infra · root:infra 0771, infrastructure data/
- docker · root:root 0755, Docker data/
- kafka · kafka:kafka 0700, kafka_data/
- mysql · mysql:mysql 0750, default mysql_data for native MySQL 8.4/
- juice · root:root 0755, default juice_cache/
- … · Other component data directories/
node_monitor also creates /var/lib/node_exporter/textfile (root:root 0755) for the node_exporter Textfile Collector. Modules publish local task/backup metrics there, such as VAULT’s vault.prom and MYSQL’s mysql.prom.
Chrony and tuned
Chrony uses the native OS configuration path: /etc/chrony.conf on EL and /etc/chrony/chrony.conf on Debian / Ubuntu. node_tuned_profile_dir selects the custom tuned profile directory: /etc/tuned/profiles on EL 10, Debian 13, and Ubuntu 26; /etc/tuned on the other currently supported platforms.
HAProxy
Pigsty starts HAProxy with its own systemd unit and manages the main configuration separately from service fragments:
To append startup arguments in /etc/default/haproxy, use EXTRAOPTS and retain the default -S /run/haproxy-master.sock. The systemd unit loads configuration with explicit -f arguments. Do not add another -f to EXTRAOPTS.
Victoria FHS
Monitoring config has moved from the legacy /etc/prometheus layout to the /infra runtime layout.
The main template is roles/infra/templates/victoria/prometheus.yml, rendered to /infra/prometheus.yml.
Pigsty copies files/victoria/bin/* to /infra/bin/ and files/victoria/rules/* to /infra/rules/. Each module registers FileSD targets under /infra/targets/*.
Victoria and Monitoring File Layout
infra/
- prometheus.yml · Victoria main configuration, Prometheus-compatible, 0644
bin · Utility scripts, 0755/
- check
- new
- reload
- status
rules · Recording and alert rules, *.yml 0644/
- agent.yml · Agent aggregation rules
- infra.yml · infra recording rules and alerts
- etcd.yml · etcd recording rules and alerts
- vault.yml · OpenBao recording rules and alerts
- node.yml · node recording rules and alerts
- pgsql.yml · pgsql recording rules and alerts
- redis.yml · redis recording rules and alerts
- minio.yml · minio recording rules and alerts
- kafka.yml · Kafka recording rules and alerts
- mysql.yml · MySQL recording rules and alerts
targets · FileSD discovery targets, *.yml 0640/
- infra · Static infra targets/
- node · Static node targets/
- pgsql · Static pgsql targets/
- pgrds · Remote PostgreSQL/RDS targets/
- redis · Static redis targets/
- minio · Static minio targets/
- mysql · Static MySQL targets/
- etcd · Static etcd targets/
- vault · Static OpenBao targets/
- ping · Static ping targets/
- kafka · Static Kafka targets/
- juice · Static JuiceFS targets/
- docker · Static Docker targets/
- patroni · Static Patroni targets when SSL is enabled/
etc/
default/
- vmetrics · victoria:infra 0644
- vlogs · victoria:infra 0644
- vtraces · victoria:infra 0644
- vmalert · victoria:infra 0644
- alertmanager · prometheus:infra 0640
- blackbox_exporter · prometheus:infra 0644
- alertmanager.yml · prometheus:infra 0644
- blackbox.yml · prometheus:infra 0644
Pigsty stores generated INFRA units in /etc/systemd/system/. These include vmetrics, vlogs, vtraces, vmalert, alertmanager, blackbox_exporter, nginx_exporter, and dnsmasq. Distribution package unit directories are not write targets for these roles.
PostgreSQL FHS
The following parameters and internal variables are related to PostgreSQL directory layout:
pg_dbsu_home: Postgres default user home directory, default:/var/lib/pgsqlpg_bin_dir: Postgres binary directory, default:/usr/pgsql/bin/pg_fs_main: Postgres primary data directory, default:/data/postgrespg_fs_backup: Postgres backup disk mount point, default:/data/backups(optional; can also be a subdirectory on primary disk)pg_data: Internal variable, fixed to the Postgres data-directory symlink/pg/datapg_cluster_dir: Derived variable,{{ pg_fs_main }}/{{ pg_cluster }}-{{ pg_version }}pg_backup_dir: Derived variable,{{ pg_fs_backup }}/{{ pg_cluster }}-{{ pg_version }}
/etc/pgbackrest and /etc/pgbouncer are owned by {{ pg_dbsu }}:postgres with mode 0750; /etc/pgbackrest/pgbackrest.conf uses 0640. The local exporter writes configuration directly to /etc/pg_exporter.yml, without creating an /etc/pg_exporter subdirectory on PG nodes.
Data File Structure
Binary File Structure
On EL-compatible distributions (using yum), PostgreSQL default installation location is:
Pigsty creates the /usr/pgsql symlink. It points to the version specified by pg_version. For example:
The default pg_bin_dir is therefore /usr/pgsql/bin/. Pigsty adds this path to the system PATH environment variable in /etc/profile.d/pgsql.sh.
On Ubuntu/Debian, the default PostgreSQL Deb package installation location is:
Pigsty also stores generated PostgreSQL runtime units in /etc/systemd/system/. These primarily include patroni.service, postgres.service, pgbouncer.service, pg_exporter.service, pgbackrest_exporter.service, and pgbouncer_exporter.service. If VIP is enabled, they also include vip-manager.service.
Pgbouncer FHS
Pgbouncer runs under the same user as {{ pg_dbsu }} (default postgres), with configs in /etc/pgbouncer.
pgbouncer.ini: main pool configuration (postgres:postgres 0640)database.txt: pooled database definitions (postgres:postgres 0600)useropts.txt: per-user connection options (postgres:postgres 0600)userlist.txt: password file maintained by/pg/bin/pgb-user(postgres:postgres 0600)pgb_hba.conf: access control file (postgres:postgres 0600)
Object Storage FHS
The MINIO module currently deploys only Silo. It retains minio_* parameter and directory names for compatibility:
Silo certificates are stored in /home/minio/.minio/certs/. The module name, role parameters, data directory, and FileSD path retain the compatible MINIO / minio_* naming.
Redis FHS
Pigsty manages Redis or Valkey with the same directory layout and instance naming.
Service units call binaries according to redis_type (/bin/* is compatible with /usr/bin/* on most distributions):
For a Redis instance named redis-test-1-6379, the related resources are as follows:
Pigsty stores generated Redis/Valkey instance and exporter units in /etc/systemd/system/. Instance units use Type=notify. Packages can provide units in distribution directories. The roles do not write to those directories.
Vault FHS
VAULT runs OpenBao as openbao.service. Its node and admin-node layout is:
OpenBao (VAULT) File Layout
etc/
openbao · root:openbao 0750/
- openbao.hcl · root:openbao 0640, OpenBao service configuration
- unseal.key · root:openbao 0640, static auto-unseal key copy
- backup.token · root:root 0600, daily snapshot token
tls · root:openbao 0750/
- ca.crt · root:openbao 0640
- server.crt · root:openbao 0640
- server.key · root:openbao 0640
profile.d/
- bao.sh · root:root 0644, CLI environment (BAO_ADDR / BAO_CACERT)
systemd/system/
- openbao.service · root:root 0644, Pigsty-rendered unit
data/vault · openbao:openbao 0700, default vault_data/
- raft · openbao:openbao 0700, embedded Raft storage/
- backup · root:root 0700, daily vault-*.snap snapshots (0600) and .backup.lock/
- var/log/openbao · openbao:openbao 0750, audit.log (0600)/
var/lib/node_exporter/textfile/
- vault.prom · Snapshot timestamp and size metrics
infra/targets/vault/
- <cluster>-<seq>.yml · victoria:infra 0640, FileSD target
Was this page helpful?
Thanks—your feedback helps us improve this page.
What got in the way? (optional)