Storage operations,
without guesswork.

01 · START HERE

Install one executable

Choose the Parto executable for your operating system and CPU architecture, put it where you keep command-line tools, and run it.

chmod +x parto_linux_amd64
sudo mv parto_linux_amd64 /usr/local/bin/parto
parto --version

chmod +x parto_darwin_arm64
sudo mv parto_darwin_arm64 /usr/local/bin/parto
parto --version

New-Item -ItemType Directory -Force "$HOME\bin"
Move-Item .\parto_windows_amd64.exe "$HOME\bin\parto.exe"
& "$HOME\bin\parto.exe" --version

Use the arm64 file on ARM64 systems and amd64 on x86-64. On Windows, add $HOME\bin to PATH only if you want to run parto.exe from any directory.

make verify
make build
./dist/parto --version

parto inspect --provider openstack [options]
parto grow --provider openstack [options] --dry-run
parto grow --provider openstack [options]

02 · READY CHECK

What Parto needs

Parto connects three parts of the operation: the machine running the command, the selected cloud provider, and the target VM. Have each one ready before the first inspection.

03 · CONNECT

Configure a cloud provider

Select --provider openstack or --provider aws explicitly for every inspect and grow operation. There is no default. The provider controls cloud discovery and volume operations; SSH or PAS still carries out guest storage work.

OpenStack

For inspect and grow, Parto searches the standard clouds.yaml locations automatically after --provider openstack is selected. Use --cloud to select a profile explicitly. Managed environment import and synchronization use an explicit --file path.

clouds:
  example-cloud:
    auth_type: password
    auth:
      auth_url: https://identity.example.com/v3
      username: example-user
      project_name: example-project
      user_domain_name: Default
      project_domain_name: Default
    region_name: RegionOne
    interface: public
    identity_api_version: 3
    verify: true

clouds:
  example-cloud:
    auth:
      password: replace-with-your-openstack-password

chmod 600 ~/.config/openstack/clouds.yaml ~/.config/openstack/secure.yaml
openstack --os-cloud example-cloud token issue
openstack --os-cloud example-cloud server show my-vm
openstack --os-cloud example-cloud server volume list my-vm

Parto requests Cinder API microversion 3.42 for online extension of attached volumes. The cloud policy and storage backend must also allow it.

AWS EBS · preview

Parto uses the AWS SDK default credential chain and requires a region. It selects one running EC2 instance by the exact Name tag passed to --vm-name, then uses its public IPv4 address when available. Private-only instances fall back to private IPv4 and require a routed network or PAS. AWS SSM is not included.

export AWS_PROFILE=production
export AWS_REGION=eu-central-1

parto inspect \
  --provider aws \
  --vm-name search-01 \
  --mountpoint /data \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa

parto inspect \
  --provider aws \
  --vm-name search-amzn-01 \
  --mountpoint /data \
  --ssh-user ec2-user \
  --ssh-key ~/.ssh/parto-amazon-linux.pem

Parto creates gp3 volumes for LVM in the instance availability zone. Nitro devices are matched by the EBS volume ID exposed as the NVMe serial; Xen-style /dev/xvd* device matching is the fallback. After EBS growth, Parto first checks the kernel-reported size and skips a generic sysfs rescan when Nitro has already exposed the requested capacity. Do not combine --provider aws with the OpenStack-only --cloud or --environment selectors.

04 · MANAGED CONNECTIONS

Import encrypted OpenStack environments

Managed environments let Parto resolve an OpenStack target from PostgreSQL. An environment binds the source cloud profile, immutable project ID, project metadata, region, and encrypted credential payload.

--cloud and --environment are both valid for inspect and grow, but they are mutually exclusive.

Start PostgreSQL for local development

docker volume create parto-postgres-data

docker run -d \
  --name parto-postgres \
  --restart unless-stopped \
  -e POSTGRES_USER=parto \
  -e POSTGRES_PASSWORD=parto-local-password \
  -e POSTGRES_DB=parto \
  -v parto-postgres-data:/var/lib/postgresql/data \
  -p 127.0.0.1:55432:5432 \
  postgres:17-alpine

export PARTO_DATABASE_URL='postgres://parto:parto-local-password@127.0.0.1:55432/parto?sslmode=disable'
openssl rand -base64 32  # Generate once and save the value.
export PARTO_MASTER_KEY='paste-the-saved-value-here'

Parto creates its environment table on first use. Keep the same master key for every later run; losing or replacing it makes existing credential records unreadable.

Import one project-scoped profile

parto environment import \
  --file ~/.config/openstack/clouds.yaml \
  --cloud example-cloud \
  --name-prefix production-search

parto environment list

Here example-cloud is the profile name in the YAML file, while production-search becomes the Parto environment name. OpenStack application credentials are project-scoped, so import one profile for each project.

Import every project available to a user

parto environment import \
  --file ~/.config/openstack/clouds.yaml \
  --cloud company \
  --name-prefix production \
  --discover-projects

--discover-projects works with username/password credentials that Keystone can re-scope. Parto imports every enabled accessible project and creates aliases such as production-search. Application credentials are project-scoped, so import those profiles one at a time without --discover-projects.

Find the exact OpenStack project name

In environment list, NAME is the Parto environment alias and may include your prefix. PROJECT is the exact name returned by Keystone, while PROJECT ID is its immutable identifier. You do not need to query PostgreSQL directly to look them up.

parto environment list | grep -i devops

parto environment list --json |
  jq -r '.environments[]
    | select(.project_name | test("devops"; "i"))
    | [.name, .project_name, .project_id, .region]
    | @tsv'

This lists environments already imported into Parto; it does not query Keystone live.

Delete one imported environment explicitly

parto environment delete production-search

Parto shows the project metadata and requires the complete environment alias before removing the encrypted PostgreSQL record. Existing operation history is preserved, and environment sync still never deletes missing projects automatically.

Synchronize imported projects safely

parto environment sync \
  --file ~/.config/openstack/clouds.yaml \
  --cloud company \
  --name-prefix production \
  --dry-run

parto environment sync \
  --file ~/.config/openstack/clouds.yaml \
  --cloud company \
  --name-prefix production

Sync matches environments by immutable project ID, adds newly accessible projects, and updates changed metadata or encrypted credentials. Renamed projects keep their Parto aliases. Projects no longer returned by Keystone are marked missing in the result but never deleted automatically.

Synchronization requires username/password credentials that Keystone can re-scope. The required --name-prefix must match the original discovery import and defines the stored environment set being reconciled. Continue importing project-scoped application credentials one at a time.

parto inspect \
  --provider openstack \
  --environment production-search \
  --vm-name my-vm \
  --mountpoint /srv/data \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa

If this is the only registered environment, omit the selector:

parto inspect \
  --provider openstack \
  --vm-name my-vm \
  --mountpoint /srv/data \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa

05 · READ ONLY

Inspect before changing anything

inspect discovers eligible data targets and runs preflight checks. It does not accept --size, run mutations, ask for approvals, or write an operation journal.

parto inspect \
  --provider openstack \
  --environment production-search \
  --vm-name my-vm \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa

parto inspect \
  --provider openstack \
  --environment production-search \
  --vm-name my-vm \
  --mountpoint /srv/data \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa

06 · OBSERVE AND INTEGRATE

Filesystem health and JSON output

Every inspected target includes filesystem capacity and inode pressure. Parto also follows the target to its physical disks and reads SMART health when the VM exposes it.

parto inspect \
  --provider openstack \
  --environment production-search \
  --vm-name my-vm \
  --mountpoint /srv/data \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa \
  --json | jq '.targets[].health'

SMART is best-effort. Parto uses smartctl when installed, supports older text-only output, and reports each underlying LVM disk separately. Missing or hidden SMART data never makes inspection fail.

07 · PLAN, THEN APPLY

Dry-run and grow

A dry run performs real read-only discovery and prints the planned cloud-provider and guest commands without applying them.

parto grow \
  --provider openstack \
  --environment production-search \
  --vm-name my-vm \
  --mountpoint /srv/data \
  --size 110 \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa \
  --dry-run

Here 110 is the new total Cinder volume size in GB.

parto grow \
  --provider openstack \
  --environment production-analytics \
  --vm-name my-vm \
  --mountpoint /data \
  --size 50 \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa \
  --dry-run

Here 50 is the size of a new Cinder volume added to the volume group.

08 · PICK THE RIGHT PATH

Filesystem and target selection

XFS is the filesystem. LVM, a partition, or a whole disk is the storage layout underneath it. The recommended selector is always the mounted filesystem: --mountpoint /data.

Internally, cloud operations and filesystem growth now use separate provider and filesystem driver contracts. OpenStack is the established provider and AWS EBS is available as a preview; XFS remains the only filesystem driver.

• Recommended: --mountpoint /data works for all supported layouts.
• LVM alternative: --lv-name data-lv accepts the plain LV name.
• Auto-detect: omit both only when exactly one eligible non-root target exists.

Data locations such as /data, /home, /mnt/storage, /opt/data, /srv, /tmp, and /var remain eligible when every other safety check passes.

09 · IMPORTANT

Understand --size

The meaning changes with the detected storage layout.

10 · ACCESS

SSH, sudo, and PAS

Direct SSH with a key

parto inspect \
  --provider openstack \
  --environment production-search \
  --vm-name my-vm \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa

Omit --ssh-key and --ssh-password to prompt for the SSH password. Add --ask-sudo-password when sudo is not passwordless.

PAS gateway

--ssh-gateway is the host you connect to. --ssh-gateway-login is the username template sent to that gateway; it must contain {target}.

parto grow \
  --provider openstack \
  --environment production-search \
  --vm-name my-vm \
  --mountpoint /srv/data \
  --size 110 \
  --ssh-gateway pas.example.com \
  --ssh-gateway-login 'centrify@{target}@user@example.com' \
  --dry-run

11 · GUARDRAILS

Safety and recovery

• The root disk and protected OS/runtime mount trees are never touched.
• Only mounted XFS filesystems are supported; other filesystems stop in preflight.
• Every mutating command requires operator confirmation.
• New guest disks are matched to exact Cinder volume IDs by serial.
• Timeouts and ambiguous outcomes stop the workflow instead of guessing.
• There is no automatic rollback, detach, delete, or LVM cleanup.

Operation journal

Every grow attempt that selects a target writes a private JSON record with mode 0600. It contains checkpoints and non-secret recovery context.

~/.local/state/parto/runs/
# or ${XDG_STATE_HOME}/parto/runs/

Read operation history from the CLI

parto runs list
parto runs list --status recovery_required --vm-name my-vm --since 24h
parto runs list --json
parto runs show <run-id>
parto runs show <run-id> --json

Run commands are read-only. --since accepts a duration such as 24h or an RFC3339 timestamp. Journal schema versioning keeps records created before v0.2.0 readable.

Ctrl-C before mutation is a normal cancellation. After mutation begins, the result may be unknown; Parto stops and prints read-only inspection commands and manual recovery guidance. With --json, the same recovery context, failed step, inspection commands, and guidance are returned as structured fields.

12 · REFERENCE

CLI reference

parto inspect --help
parto grow --help
parto environment --help
parto environment import --help
parto environment list --help
parto environment delete --help
parto environment sync --help
parto runs --help