# Running bees

## Setup

If you don't want to use the helper script `scripts/beesd` to setup and configure bees, here's how you manually setup bees.

Create a directory for bees state files:

        export BEESHOME=/some/path
        mkdir -p "$BEESHOME"

Create an empty hash table (your choice of size, but it must be a multiple of 128KB). This example creates a 1GB hash table:

        truncate -s 1g "$BEESHOME/beeshash.dat"
        chmod 700 "$BEESHOME/beeshash.dat"

bees can only process the root subvol of a btrfs with nothing mounted over top. If the bees argument is not the root subvol directory, bees will just throw an exception and stop.

Use a separate mount point, and let only bees access it:

        UUID=3399e413-695a-4b0b-9384-1b0ef8f6c4cd
        mkdir -p /var/lib/bees/$UUID
        mount /dev/disk/by-uuid/$UUID /var/lib/bees/$UUID -osubvol=/

If you don't set BEESHOME, the path "`.beeshome`" will be used relative to the root subvol of the filesystem. For example:

        btrfs sub create /var/lib/bees/$UUID/.beeshome
        truncate -s 1g /var/lib/bees/$UUID/.beeshome/beeshash.dat
        chmod 700 /var/lib/bees/$UUID/.beeshome/beeshash.dat

You can use any relative path in `BEESHOME`. The path will be taken relative to the root of the deduped filesystem (in other words it can be the name of a subvol):

        export BEESHOME=@my-beeshome
        btrfs sub create /var/lib/bees/$UUID/$BEESHOME
        truncate -s 1g /var/lib/bees/$UUID/$BEESHOME/beeshash.dat
        chmod 700 /var/lib/bees/$UUID/$BEESHOME/beeshash.dat

## Configuration

There are some runtime configurable options using environment variables:

- BEESHOME: Directory containing bees state files:
  - beeshash.dat | persistent hash table. Must be a multiple of 128KB, and must be created before bees starts.
  - beescrawl.dat | state of SEARCH_V2 crawlers. ASCII text. bees will create this.
  - beesstats.txt | statistics and performance counters. ASCII text. bees will create this.
- BEESSTATUS: File containing a snapshot of current bees state: performance counters and current status of each thread. The file is meant to be human readable, but understanding it probably requires reading the source. You can watch bees run in realtime with a command like:

      watch -n1 cat $BEESSTATUS

Other options (e.g. interval between filesystem crawls) can be configured in `src/bees.h` or on the command line.

## Running

Reduce CPU and IO priority to be kinder to other applications sharing this host (or raise them for more aggressive disk space recovery). If you use cgroups, put `bees` in its own cgroup, then reduce the `blkio.weight` and `cpu.shares` parameters. You can also use `schedtool` and `ionice` in the shell script that launches `bees`:

        schedtool -D -n20 $$
        ionice -c3 -p $$

You can also use the `--loadavg-target` and `--thread-min` options to further control the impact of bees on the rest of the system.

Let the bees fly:

        for fs in /var/lib/bees/*-*-*-*-*/; do
                bees "$fs" >> "$fs/.beeshome/bees.log" 2>&1 &
        done

You'll probably want to arrange for `/var/log/bees.log` to be rotated periodically. You may also want to set umask to 077 to prevent disclosure of information about the contents of the filesystem through the log file.

There are also some shell wrappers in the `scripts/` directory.