Basic Installation

Here’s the steps you need to follow to get a working installation on your target host. This might seem like an arduous process, but if you’re accustomed to a Linux command prompt and ideally also Ansible, it boils down to these steps:

  • Create your working directory.

  • Call the Ansible installer script, if you don’t have it available yet.

  • Enable a SSH sudo account on your deployment target.

  • Create and edit two Ansible config files.

  • Run the playbook and wait a bit.

  • Enjoy your working and secure seedbox.

And once you got it working, moving to or adding another machine is easy and almost no work, just add that host and run the playbooks for it.

Note that this cannot be an Ansible or Linux shell 101, so if these topics are new for you refer to the usual sources like The Debian Administrator’s Handbook, The Linux Command Line, The Art of Command Line, and the Ansible Documentation.

Checking Out the Code

To work with the playbooks, you need a local copy of them. Unsurprisingly, you also need git installed for this, to create that local copy (a/k/a clone the repository).

Executing these commands on your workstation takes care of that:

which git || sudo apt-get install git
mkdir -p ~/src; cd $_
git clone "https://github.com/pyroscope/pimp-my-box.git"
cd "pimp-my-box"

Installing Ansible

Ansible must be installed on the workstation from where you control your target hosts. This can also be the target host itself, if you don’t have a local computer running on Linux, Mac OSX, or Windows 10 with WSL installed. In that case, use a personal account on that machine, or create an ansible one – any part of the documentation that refers to ‘the workstation’ then means that account.

See the Ansible Installation Documentation for how to install it using the package manager of your platform. Make sure you get the right version that way, the playbooks are tested using Ansible 2.9.5. Read Update to Ansible2 on Your Workstation when you have an existing workdir from before February 2020.

The recommended way to install Ansible is to put it into your home directory. The following commands just require Python 3.5+ to be installed on your system. The installation is easy to get rid of (everything is contained within a single directory). When you have no ~/.ansible.cfg yet (which you very likely do not), one is added.

Enter / copy+paste this command into a shell prompt on your workstation, within the ‘pimp-my-box’ directory!

./scripts/install_ansible.sh

Providing SSH Access for Ansible

For a dedicated server, the first step is to create an account Ansible can use to perform its work. Log into your server as root and call these commands:

account=setup
groupadd $account
useradd -g $account -G $account,users -c "Ansible remote user" \
        -s /bin/bash --create-home $account
eval chmod 0750 ~$account
passwd -l $account

Calling the following command as root on the target host will grant password-less sudo to the new account:

# Give password-less sudo permissions to the "setup" user
echo >/etc/sudoers.d/setup "setup ALL=(ALL) NOPASSWD:ALL"

In case you prefer password-protected sudo, leave out the NOPASSWD:, and also set a password using passwd setup.

The setup account must allow login using the id_rsa key, or another key you create on your workstation. See here for establishing working SSH access based on a pubkey login, if you’ve never done that before.

Finally, the last snippet of SSH configuration goes into ~/.ssh/config of your workstation account, add these lines providing details on how to connect to your target host via SSH (and replace the text in ALL_CAPS by the correct value):

Host my-box
    HostName IP_ADDRESS_OR_DOMAIN_OF_TARGET
    Port 22
    User setup
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes

Now to test that you did everything right, call the below ssh command on your workstation, and verify that you get the output as shown:

$ ssh my-box "sudo id"
uid=0(root) gid=0(root) groups=0(root)

In case you’re asked for a password, enter the one you’ve set on the setup account.

Setting Up Your Environment

Now with Ansible installed and able to connect via SSH, you next need to configure the target host (by default named my-box) and its specific attributes (the so-called host vars). There is an example in host_vars/rpi/main.yml for a default Raspberry Pi setup which is used as a template.

To create the necessary files, call this command:

./scripts/add_host.sh

If you already have an Ansible inventory (i.e. hosts file), your configured editor will open it – else a suitable default is created. Make sure you add your target’s name to the [box] group, if it’s missing.

Next the editor will open with main.yml, fill in the values as described in the first few lines of the file. In a final step, you need to enter the sudo password of your target server.

Afterwards, you have these files in your working directory: hosts, host_vars/my-box/main.yml, and host_vars/my-box/secrets.yml. If you don’t understand what is done here, read the Ansible documentation again, specifically the “Getting Started” page.

Now we can check your setup and that Ansible is able to connect to the target and do its job there. For this, call the command as shown after the $, and it should print what OS you have installed on the target(s), like shown in the example.

$ ansible box -i hosts -m setup -a "filter=*distribution*"
my-box | success >> {
    "ansible_facts": {
        "ansible_distribution": "Ubuntu",
        "ansible_distribution_major_version": "14",
        "ansible_distribution_release": "trusty",
        "ansible_distribution_version": "14.04"
    },
    "changed": false
}

If anything goes wrong, add -vvvv to the ansible command for more diagnostics, and also check your ~/.ssh/config and the Ansible connection settings in your host_vars. If it’s a connection problem, try to directly call ssh -vvvv my-box and if that succeeds, also make sure you can become root via sudo su -. If not, read the resources linked at the start of this chapter, and especially the SSH Essentials.

Using the System Python Interpreter

By default, Python 2.7.13 is installed because that version handles SSL connections according to current security standards; the version installed in your system often does not. This has an impact on e.g. FlexGet’s handling of https feeds.

If you want to use the system’s Python interpreter, add these variables to your host vars:

pyenv_enabled: false
python_bin: /usr/bin/python2
venv_bin: /usr/bin/virtualenv

Doing so is recommended on Xenial (has 2.7.12), Jessie (2.7.9), or Stretch (2.7.13).

Running the Playbook

To execute the playbook, call ansible-playbook -i hosts site.yml. The initial installation will take a while, so be patient.

If your Linux release isn’t supported with a pre-built package, you’ll see a message like the following:

WARNING - No DEB package URL defined for '‹platform›', you need to install /opt/rtorrent manually!

In that case, compile a binary yourself. If you want to run a rTorrent-PS version that is not yet released to GitHub Releases, do the same.

If you added more than one host into the box group and want to only address one of them, use ansible-playbook -i hosts -l ‹hostname› site.yml. Add (multiple) -v to get more detailed information on what each task does.

Starting rTorrent

As mentioned before, after successfully running the Ansible playbook, a fully configured setup is found on the target. So to start rTorrent, log in as the rtorrent user and start this command:

tmux -2u new -n rT-PS -s rtorrent "~/rtorrent/start; exec bash"

To detach from this session (meaning rTorrent continues to run), press Ctrl-a followed by d.

If you get rtorrent: command not found when calling above tmux command, then a pre-built Debian package is not available for your OS distribution and you need to build from source (see previous section). You can check explicitly with the following command:

$ dpkg -l rtorrent-ps
dpkg-query: no packages found matching rtorrent-ps

Changing Configuration Defaults

Customizing Your Setup

A good way to provide customizations is writing your own playbooks. Create a separate project in your own git repository. In that project, you can provide your versions of existing files, add your own helper scripts, and so on. Model it after this repository, and consult the Ansible documentation. You can reuse your inventory, by passing -i ../pimp-by-box/hosts to the playbook calls, or by setting the ANSIBLE_INVENTORY environment variable.

As described in this and the following sections, some key config files are designed to be replaced in this way. Just be aware that once you copy them, you also have to manage them yourself, and merge with changes made to the master in this repo!

Handling Top-Level Config Files

Once created, the file rtorrent.rc is only overwritten when you provide -e force_cfg=yes on the Ansible command line. This gives you the opportunity to easily refresh the main configuration in rtorrent.rc from this repository. But it also gives you the option to provide your own custom version by other means, e.g. your own additional playbook, without having that version constantly overwritten.

However, additional files in rtorrent.d/ or the _rtlocal.rc include file are the intended places to make customizations, so it’s advisable to always add -e force_cfg=yes on updates.

The _rtlocal.rc file, which is included by rtorrent.rc after the standard configuration includes in rtorrent.d/, is never overwritten. So it’s easy and safe to provide your own version of _rtlocal.rc from a custom playbook. Or apply customizations manually, by editing ~rtorrent/rtorrent/_rtlocal.rc – these will not be reverted by updating from the repository.

A typical use of _rtlocal.rc is to change how long log files are kept uncompressed, here the default of 2 days is reduced to just one:

pyro.log_archival.days.set = 1

Adding Drop-In Files

Another way to customize rTorrent is to use the ~/rtorrent/rtorrent.d directory. Just place any file with a .rc extension there, and it will be loaded on the next restart. This is ideally suited for custom playbooks, which can just add new files to extend the default configuration.

That directory also contains most of the extra rTorrent configuration that comes with pimp-my-box. For example, by default terminating rTorrent via ^Q gets disabled in the disable-control-q.rc file, replacing it by ^X q=, which you won’t type by accident.

To restore the rTorrent default, run this command as the rtorrent user (or put the line into that file via Ansible):

echo >>~/rtorrent/rtorrent.d/.rcignore "disable-control-q.rc"

Then restart rTorrent.

Optional Applications & More

See Optional Features on how to activate add-ons like ruTorrent, and Advanced Topics for more details about the box installation and its features.