File Hierarchy
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:
#------------------------------------------------------------------------------
# pigsty
# ^-----@app # Extra application resources and examples
# ^-----@bin # Utility scripts
# ^-----@docs # Documentation (docsify-compatible)
# ^-----@files # Ansible file resources
# ^-----@victoria # Victoria rules and ops scripts (bin/rules)
# ^-----@grafana # Grafana dashboards
# ^-----@postgres # /pg/bin/ scripts
# ^-----@migration # PGSQL migration task definitions
# ^-----@pki # Self-signed CA and certificates
# ^-----@roles # Ansible role implementations
# ^-----@templates # Ansible template files
# ^-----@vagrant # Vagrant sandbox VM templates
# ^-----@terraform # Terraform cloud VM provisioning templates
# ^-----configure # Configuration wizard script
# ^-----ansible.cfg # Ansible default configuration
# ^-----pigsty.yml # Pigsty default configuration file
# ^-----*.yml # Ansible playbooks
#------------------------------------------------------------------------------
# /infra -> /data/infra # infra runtime symlink
# /data/infra # root:infra 0771
# ^-----@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 config
#------------------------------------------------------------------------------
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
# ^-----@mongo # (local_user) 0755, Mongo/FerretDB certs
# ^-----@mysql # (local_user) 0755, MySQL certs (placeholder)
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 # Symlink to system trust anchors
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)
# ^-----@mongo # mongo 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.
Each component’s default data directory is located under this data directory:
/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)
# ^-----@... # Other component data directories
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
# ^-----@mongo # mongo 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)
PostgreSQL FHS
The following parameters 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_data: Postgres data directory, default:/pg/datapg_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_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
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)
Redis FHS
Pigsty provides basic support for Redis deployment and monitoring.
Redis binaries are usually installed by the system package manager (service paths use /bin/*, with /usr/bin/* compatibility symlinks on most distros):
redis-server
redis-cli
redis-sentinel
redis-check-rdb
redis-check-aof
redis-benchmark
/usr/libexec/redis-shutdown
For a Redis instance named redis-test-1-6379, the related resources are as follows:
/usr/lib/systemd/system/redis-test-1-6379.service # root:root 0644 (Debian: /lib/systemd/system)
/etc/redis/ # redis:redis 0700
/etc/redis/redis-test-1-6379.conf # redis:redis 0700
/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
For Ubuntu/Debian, the default systemd service directory is /lib/systemd/system/ instead of /usr/lib/systemd/system/.
Feedback
Was this page helpful?
Thanks for the feedback! Please let us know how we can improve.
Sorry to hear that. Please let us know how we can improve.