# cockroach debug ballast

The `cockroach debug ballast` command creates a large, unused file that you can place in a node's storage directory. In the case that a node runs out of disk space and shuts down, you can delete the ballast file to free up enough space to be able to restart the node.

- Do not run `cockroach debug ballast` with a unix `root` user. Doing so brings the risk of mistakenly affecting system directories or files.
- Do not name the target file similar to a block device in `/dev`. Doing so brings the risk of mistyping a `/dev` prefix into the command and thereby corrupting a filesystem.
- In addition to placing a ballast file in each node's storage directory, it is important to actively monitor remaining disk space.
- Ballast files may be created in many ways, including the standard `dd` command. `cockroach debug ballast` uses the `fallocate` system call when available, so it will be faster than `dd`.

## Subcommands

While the `cockroach debug` command has a few subcommands, users are expected to use only the `zip`, `encryption-active-key`, `merge-logs`, and `ballast` subcommands.

The other `debug` subcommands are useful only to CockroachDB's developers and contributors.

## Synopsis

Create a ballast file:

    $ cockroach debug ballast [path to ballast file] [flags]

View help:

    $ cockroach debug ballast --help

## Flags

Flag | Description
--- | ---
`--size` `-z` | The amount of space to fill, or to leave available, in a node's storage directory via a ballast file. Positive values equal the size of the ballast file. Negative values equal the amount of space to leave after creating the ballast file. This can be a percentage (notated as a decimal or with %) or any bytes-based unit, for example: `--size=1000000000 ----> 1000000000 bytes` `--size=1GiB ----> 1073741824 bytes` `--size=5% ----> 5% of available space` `--size=0.05 ----> 5% of available space` `--size=.05 ----> 5% of available space` Default: `1GB`

## Examples

### Create a 1GB ballast file (default)

    $ cockroach debug ballast cockroach-data/ballast.txt

### Create a ballast file of a different size

    $ cockroach debug ballast cockroach-data/ballast.txt --size=2GB

## See also

- Other Cockroach Commands
- Troubleshooting Overview
- Production Checklist