File Hierarchy
How Pigsty’s file system structure is designed and organized, and directory structures used by each module.
How Pigsty’s file system structure is designed and organized, and directory structures used by each module.
Pigsty FHS
Pigsty’s home directory is located at ~/pigsty by default. The file structure within this directory is as follows:
- app/
- Application template resources
- bin/
- Management and operations scripts
- files/
- victoria/
- Rules and operations scripts
- grafana/
- postgres/
- PostgreSQL management scripts
- migration/
- Data-migration task definitions
- pki/
- Self-signed CA and certificates
- roles/
- Ansible role implementations
- templates/
- vagrant/
- Vagrant sandbox definitions
- terraform/
- Terraform cloud-resource templates
- configure
- ansible.cfg
- pigsty.yml
- *.yml
/infra is a runtime symlink to /data/infra, which keeps observability data and generated configuration together:
metrics/ # VictoriaMetrics TSDB data
logs/ # VictoriaLogs data
traces/ # VictoriaTraces data
alertmgr/ # AlertManager data
rules/ # Rule definitions, including agent.yml
targets/ # FileSD monitoring targets
dashboards/ # Grafana dashboard definitions
datasources/ # Grafana datasource definitions
prometheus.yml # Victoria Prometheus-compatible 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. This key is generated by the ca role during deploy.yml or infra.yml execution.
# pigsty/files/pki # (local_user) 0755
# ^-----@ca # (local_user) 0700
# ^[email protected] # 0600, CRITICAL: keep secret
# ^[email protected] # 0644, CRITICAL: trust anchor
# ^-----@csr # (local_user) 0755, CSRs
# ^-----@misc # (local_user) 0755, misc/issued certs
# ^-----@etcd # (local_user) 0755, ETCD certs
# ^-----@minio # (local_user) 0755, MinIO certs
# ^-----@nginx # (local_user) 0755, Nginx SSL certs
# ^-----@infra # (local_user) 0755, infra client certs
# ^-----@pgsql # (local_user) 0755, PostgreSQL certs
# ^-----@kafka # (local_user) 0755, Kafka server certs
# ^-----@mysql # (local_user) 0755, MySQL server certs
Nodes managed by Pigsty will have the following certificate files installed:
/etc/pki/ca.crt # root:root 0644, root cert on all nodes
/etc/pki/ca-trust/source/anchors/ca.crt # EL system trust anchor
/usr/local/share/ca-certificates/ca.crt # Debian/Ubuntu system trust anchor
All infra nodes will have the following certificates:
/etc/pki/infra.crt # root:infra 0644, infra node cert
/etc/pki/infra.key # root:infra 0640, infra node key
When your admin node fails, the files/pki directory and pigsty.yml file should be available on the backup admin node. You can use rsync to achieve this:
# run on meta-1, rsync to meta2
cd ~/pigsty;
rsync -avz ./ meta-2:~/pigsty
INFRA FHS
The infra role creates infra_data (default: /data/infra) and creates a symlink /infra -> /data/infra.
/data/infra permissions are root:infra 0771; subdirectories default to *:infra 0750 unless overridden:
# /infra -> /data/infra
# /data/infra # root:infra 0771
# ^-----@pgadmin # 5050:5050 0700
# ^-----@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 # grafana:infra 0750
# ^-----@metrics # victoria:infra 0750
# ^-----@logs # victoria:infra 0750
# ^-----@traces # victoria:infra 0750
# ^-----@bin # victoria:infra 0750
# ^-----check|new|reload|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
# ^-----minio.yml # victoria:infra 0644
# ^-----kafka.yml # victoria:infra 0644
# ^-----mysql.yml # victoria:infra 0644
# ^-----@targets # victoria:infra 0750
# ^-----@infra # infra targets (files 0640)
# ^-----@node # node targets (files 0640)
# ^-----@ping # ping targets (files 0640)
# ^-----@etcd # etcd 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.
NODE FHS
The node data directory is specified by node_data, defaulting to /data, owned by root:root with mode 0755.
Most core components place their default data directories here. Some pilot modules use fixed paths of their own; native MySQL 8.4 currently uses /var/lib/mysql.
/data # root:root 0755
# ^-----@postgres # postgres:postgres 0700 (default pg_fs_main)
# ^-----@backups # postgres:postgres 0700 (default pg_fs_backup)
# ^-----@redis # redis:redis 0700 (shared by multiple instances)
# ^-----@minio # minio:minio 0750 (single-node single-disk mode)
# ^-----@etcd # etcd:etcd 0700 (etcd_data)
# ^-----@infra # root:infra 0771 (infra module data directory)
# ^-----@docker # root:root 0755 (Docker data directory)
# ^-----@kafka # kafka:kafka 0700 (kafka_data)
# ^-----@... # Other component data directories
HAProxy
Pigsty starts HAProxy with its own systemd unit and manages the main configuration separately from service fragments:
/etc/systemd/system/haproxy.service # systemd unit rendered by Pigsty
/etc/haproxy/haproxy.cfg # HAProxy main configuration
/etc/haproxy/conf.d/*.cfg # node and PostgreSQL service fragments
/etc/default/haproxy # optional user environment file; Pigsty does not create it
To append startup arguments in /etc/default/haproxy, use EXTRAOPTS and retain the default -S /run/haproxy-master.sock. The systemd unit already loads configuration with explicit -f arguments, so 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.
files/victoria/bin/* and files/victoria/rules/* are synced to /infra/bin/ and /infra/rules/, while each module registers FileSD targets under /infra/targets/*.
# /infra
# ^-----prometheus.yml # Victoria main config (Prometheus-compatible) 0644
# ^-----@bin # Utility scripts (check/new/reload/status) 0755
# ^-----@rules # Recording and alerting rules (*.yml 0644)
# ^-----agent.yml # Agent pre-aggregation rules
# ^-----infra.yml # infra rules and alerts
# ^-----etcd.yml # etcd rules and alerts
# ^-----node.yml # node rules and alerts
# ^-----pgsql.yml # pgsql rules and alerts
# ^-----redis.yml # redis rules and alerts
# ^-----minio.yml # minio rules and alerts
# ^-----kafka.yml # kafka rules and alerts
# ^-----mysql.yml # mysql rules and alerts
# ^-----@targets # FileSD targets (*.yml 0640)
# ^-----@infra # infra static targets
# ^-----@node # node static targets
# ^-----@pgsql # pgsql static targets
# ^-----@pgrds # pgsql remote RDS targets
# ^-----@redis # redis static targets
# ^-----@minio # minio static targets
# ^-----@mysql # mysql static targets
# ^-----@etcd # etcd static targets
# ^-----@ping # ping static targets
# ^-----@kafka # kafka static targets
# ^-----@juice # juicefs static targets
# ^-----@docker # docker static targets
# ^-----@patroni # patroni static targets (when SSL enabled)
# /etc/default/vmetrics # vmetrics startup args (victoria:infra 0644)
# /etc/default/vlogs # vlogs startup args (victoria:infra 0644)
# /etc/default/vtraces # vtraces startup args (victoria:infra 0644)
# /etc/default/vmalert # vmalert startup args (victoria:infra 0644)
# /etc/alertmanager.yml # alertmanager main config (prometheus:infra 0644)
# /etc/default/alertmanager # alertmanager env (prometheus:infra 0640)
# /etc/blackbox.yml # blackbox main config (prometheus:infra 0644)
# /etc/default/blackbox_exporter # blackbox env (prometheus:infra 0644)
Pigsty-rendered INFRA units are consistently stored in /etc/systemd/system/, including 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 }}
#--------------------------------------------------------------#
# Working assumptions:
# {{ pg_fs_main }} primary data directory, default: `/data/postgres` [SSD]
# {{ pg_fs_backup }} backup data disk, default: `/data/backups` [HDD]
#--------------------------------------------------------------#
# Default config (pg_cluster=pg-test, pg_version=18):
# pg_fs_main = /data/postgres High-speed SSD
# pg_fs_backup = /data/backups Cheap HDD (optional)
#
# /pg -> /data/postgres/pg-test-18
# /pg/data -> /data/postgres/pg-test-18/data
# /pg/backup -> /data/backups/pg-test-18/backup
#--------------------------------------------------------------#
- name: create pgsql directories
tags: pg_dir
become: true
block:
- name: create pgsql directories
file: path={{ item.path }} state=directory owner={{ item.owner|default(pg_dbsu) }} group={{ item.group|default('postgres') }} mode={{ item.mode }}
with_items:
- { path: "{{ pg_fs_main }}" ,mode: "0700" }
- { path: "{{ pg_fs_backup }}" ,mode: "0700" }
- { path: "{{ pg_cluster_dir }}" ,mode: "0700" }
- { path: "{{ pg_cluster_dir }}/bin" ,mode: "0700" }
- { path: "{{ pg_cluster_dir }}/log" ,mode: "0750" }
- { path: "{{ pg_cluster_dir }}/tmp" ,mode: "0700" }
- { path: "{{ pg_cluster_dir }}/cert" ,mode: "0700" }
- { path: "{{ pg_cluster_dir }}/conf" ,mode: "0700" }
- { path: "{{ pg_cluster_dir }}/data" ,mode: "0700" }
- { path: "{{ pg_cluster_dir }}/spool" ,mode: "0700" }
- { path: "{{ pg_backup_dir }}/backup" ,mode: "0700" }
- { path: "/var/run/postgresql" ,owner: root, group: root, mode: "0755" }
- name: link pgsql directories
file: src={{ item.src }} dest={{ item.dest }} state=link
with_items:
- { src: "{{ pg_backup_dir }}/backup" ,dest: "{{ pg_cluster_dir }}/backup" }
- { src: "{{ pg_cluster_dir }}" ,dest: "/pg" }
Data File Structure
# Physical directories
{{ pg_fs_main }} /data/postgres # postgres:postgres 0700, primary data directory
{{ pg_cluster_dir }} /data/postgres/pg-test-18 # postgres:postgres 0700, cluster directory
/data/postgres/pg-test-18/bin # postgres:postgres 0700 (scripts root:postgres 0755)
/data/postgres/pg-test-18/log # postgres:postgres 0750, logs
/data/postgres/pg-test-18/tmp # postgres:postgres 0700, temp files
/data/postgres/pg-test-18/cert # postgres:postgres 0700, certs
/data/postgres/pg-test-18/conf # postgres:postgres 0700, config index
/data/postgres/pg-test-18/data # postgres:postgres 0700, main data
/data/postgres/pg-test-18/spool # postgres:postgres 0700, pgBackRest spool
/data/postgres/pg-test-18/backup # -> /data/backups/pg-test-18/backup
{{ pg_fs_backup }} /data/backups # postgres:postgres 0700, optional backup mount
{{ pg_backup_dir }} /data/backups/pg-test-18 # postgres:postgres 0700, cluster backup directory
/data/backups/pg-test-18/backup # postgres:postgres 0700, actual backup location
# Symlinks
/pg -> /data/postgres/pg-test-18 # pg root symlink
/pg/data -> /data/postgres/pg-test-18/data # pg data directory
/pg/backup -> /data/backups/pg-test-18/backup # pg backup directory
Binary File Structure
On EL-compatible distributions (using yum), PostgreSQL default installation location is:
/usr/pgsql-${pg_version}/
Pigsty creates a symlink named /usr/pgsql pointing to the actual version specified by the pg_version parameter, for example:
/usr/pgsql -> /usr/pgsql-18
Therefore, the default pg_bin_dir is /usr/pgsql/bin/, and this path is added to the system PATH environment variable, defined in: /etc/profile.d/pgsql.sh.
export PATH="/usr/pgsql/bin:/pg/bin:$PATH"
export PGHOME=/usr/pgsql
export PGDATA=/pg/data
On Ubuntu/Debian, the default PostgreSQL Deb package installation location is:
/usr/lib/postgresql/${pg_version}/bin
Pigsty-rendered PostgreSQL runtime units are likewise stored in /etc/systemd/system/. They primarily include patroni.service, postgres.service, pgbouncer.service, pg_exporter.service, pgbackrest_exporter.service, pgbouncer_exporter.service, and vip-manager.service when VIP is enabled.
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-userpgb_hba.conf: access control file (postgres:postgres 0600)
/etc/pgbouncer/ # postgres:postgres 0750
/etc/pgbouncer/pgbouncer.ini # postgres:postgres 0640
/etc/pgbouncer/database.txt # postgres:postgres 0600
/etc/pgbouncer/useropts.txt # postgres:postgres 0600
/etc/pgbouncer/userlist.txt # postgres:postgres (managed by pgb-user)
/etc/pgbouncer/pgb_hba.conf # postgres:postgres 0600
/pg/log/pgbouncer # postgres:postgres 0750
/var/run/postgresql # {{ pg_dbsu }}:postgres 0755 (managed by tmpfiles)
Object Storage FHS
The MINIO module currently deploys only Silo, while retaining minio_* parameter and directory names for compatibility:
/etc/default/silo # root:minio 0640, service environment
/etc/systemd/system/silo.service # root:root 0644, rendered by Pigsty
/data/minio/ # minio:minio 0750, default data directory
/infra/targets/minio/<cluster>-<seq>.yml # victoria:infra 0640, FileSD target
/home/minio/.mcli/config.json # mcli alias; also written for the execution user
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):
/bin/redis-server /bin/redis-cli # redis_type: redis
/bin/valkey-server /bin/valkey-cli # redis_type: valkey
For a Redis instance named redis-test-1-6379, the related resources are as follows:
/etc/systemd/system/redis-test-1-6379.service # root:root 0644, rendered by Pigsty
/etc/systemd/system/redis_exporter.service # root:root 0644, rendered by Pigsty
/etc/redis/ # redis:redis 0700
/etc/redis/redis-test-1-6379.conf # redis:redis 0600
/data/redis/ # redis:redis 0700
/data/redis/redis-test-1-6379 # redis:redis 0700
/data/redis/redis-test-1-6379/redis-test-1-6379.rdb # RDB file
/data/redis/redis-test-1-6379/redis-test-1-6379.aof # AOF file
/var/log/redis/ # redis:redis 0700
/var/log/redis/redis-test-1-6379.log # logs
/var/run/redis/ # redis:redis 0700 (tmpfiles creates 0755 at boot)
/var/run/redis/redis-test-1-6379.pid # PID
Pigsty-rendered Redis/Valkey instance and exporter units are consistently stored in /etc/systemd/system/, and instance units use Type=notify. Package-provided units may still live in distribution directories, but those are not role write targets.