Skip to content

Latest commit

 

History

History
137 lines (97 loc) · 5.54 KB

README.md

File metadata and controls

137 lines (97 loc) · 5.54 KB
Raw

BSDops

DebOps-derived reusable, integrated Ansible configs for FreeBSD-based machines.

See Design Goals for more info on what exactly this project is trying to achieve.

Note: This is currently in a very early stage of development. Currently only debops bootstrap is fully "FreeBSD-ified", and "extensive testing" is a dream.

Why should I use this, especially when I know it will break?

Because:

  1. you should use configuration management
  2. Ansible is a decent configuration management option, so you likely want to use that
  3. If you're going to use Ansible, you will have to write your own roles, because there is no "ready-made" option for FreeBSD
  4. If you're going to write your own roles, you might as well start with a decent base that can benefit other people too, such as this one :-)

How to use

1. Install

  1. Install debops normally:

  2. Create a project directory for your configuration:

    mkdir my-project
cd my-project
# if you installed with pipenv: pipenv shell
debops-init .

  3. Tell debops to use my fork instead of the official DebOps repo: put it into a debops/ subdirectory:

    # (inside the project directory)
git clone https://github.com/AnotherKamila/debops debops
# or git submodule add ...
# or ln -s ...

    Or with git subrepo:

    git subrepo clone https://github.com/anotherkamila/debops.git debops/

    (this repository uses git subrepo)

  4. Copy the file ansible/inventory/group_vars/freebsd/bsdops_required.yml into your project. This file contains important settings that adapt DebOps defaults for FreeBSD.

    (In the future, manually copying the variables will not be necessary, but bear with me for a while.)

2. Bootstrap host(s)

  1. Add your host(s) to the inventory: $EDITOR ansible/inventory/hosts

    • All FreeBSD hosts need to be in a group named freebsd (this is used to run the right OS-specific things).
      Example inventory file: 
      [freebsd]
freebsdhost.example.org

# Linux-based hosts still work
[linux]
debianhost.example.org
devuanhost.example.org

[debops_all_hosts:children]
freebsd
linux
      Note: You can use the same project/inventory for FreeBSD-based and Linux-based hosts, BSDops tries to be compatible.

  2. Bootstrap your host(s): Make sure that you can log in without password (--ask-pass doesn't work with FreeBSD).
    For example: ssh-copy-id myhost. Then run:

    debops bootstrap <parameters-needed-to-connect> [--limit myhost]
# examples:
# debops bootstrap -u root  # if you can log in as root
# debops bootstrap -u admin --become --ask-become-pass  # if you can log in as a user that has sudo

3. Use DebOps roles to effortlessly set up your host(s)

This feature will be available in a future version :D

Seriously though: This project is a WIP and so far I have only "FreeBSD-ified" the roles used in the bootstrap playbook. Other roles might or might not work (often e.g. paths or package names might be wrong). However, patching these higher-level roles should be relatively straight-forward in many cases. So: Try it, see what breaks, and send a pull request!

The next roles I intend to convert are generic basic things like firewalling. My use-case is a router box, so the things I'll work on next will be going in that direction. If you want something else, I'll happily accept pull requests :-)

See Common Differences for a quick list of things which are often different on Linux vs FreeBSD and how I handle them when FreeBSD-ifying roles.

Configuration

Everything is the same as DebOps, so in theory this section is unnecessary. However, as a quick reference, this is a list of things one might want to change often:

  • bootstrap__admin_system: set to False to have the automatically created admin user get a home directory under /home instead of under /usr/local.

Compatibility with Debian-based hosts

Ideally, my DebOps fork should work the same as original DebOps on non-FreeBSD hosts -- the idea is to add new functionality without breaking existing stuff. That said, I do not currently have the capacity to test that much. So, it may break. But if it does break, it's a bug, so please report it (ideally with a patch :-)).

Development

This repo contains the documentation (so, this README) and an example debops project that you can use as a starting point. The repo with my patched version of debops lives at anotherkamila/debops.

Development workflow with git subrepo:

git subrepo clone git@github.com:anotherkamila/debops.git debops/  # use your fork
[hack hack]
[git commit ...]
git subrepo push debops
git push

Updating debops from upstream with minimum suffering:

git subrepo push debops
cd WHEREVER_I_CHECKED_OUT_DEBOPS_REPO_AS_TOPLEVEL
git pull origin master
git fetch --all
git merge upstream/master
git push
cd BACK_TO_HERE
git subrepo pull debops

License

The contents of this repository EXCLUDING the debops/ directory is licensed under BSD 2-clause license, as indicated by the LICENSE file.

As DebOps is licensed under GPL, the debops/ directory and my changes in it are licensed under GPL.