This document is a quick overview of FreeBSD Jails at the ASF. Intended for PMCs with some notes for infra folk too. It is incomplete, please email infrastructure@ with any queries you might have and to therefore help us complete this document.

Note that virtual machines are also available for operating systems other than FreeBSD. We don't seem to have documentation on those so far but as an example INFRA-4515 should provide enough info about how to get and use such a VM.

Here are some notes to assist the PMCs to manage their jail.

Creating users in a jail

Your PMC chair is root of your jail, and can add other users.

Note: When creating accounts, please reuse username and userid from people.a.o

$ sudo pw user add <username> -u $uid -m -d /home/<username> -s /bin/bash

$ sudo passwd <username>

Important: All accounts MUST log in using a public/private (RSA or DSA) key pair, see below. Users must add their keys to svn at https://svn.apache.org/repos/infra/infrastructure/trunk/ssh_keys/people/ so that zone admins can copy them after checking that a key belongs to the corresponding user.

Setting up key-based logins

The standard process for this is

  • Username/userid must match LDAP, id -u <username> on people.apache.org can be used to get that userid.

  • User must be in the sshusers group, check with the id command on the VM

  • SSH public key must be added to id.apache.org. Can be checked with ldapsearch -xLLL uid=<username> sshPublicKey on people.apache.org for example.

  • On some VMs, SSH public key must be copied to /etc/ssh/ssh_keys - check that folder to see if your VM is setup in that way, and if it's the case the /root/bin/asf-sshkeys.sh script might be useful.

  • If SSH public key is ok and user gets an access denied for this host error, ask infra to grant them access.

  • To check the SSH key of the VM use /usr/local/bin/ssh-keyscan <VM hostname> on people.apache.org. You can use zsh -c 'ssh-keygen -lf =(ssh-keygen devicemap-vm.apache.org)' to get the fingerprint only.

  • Password must be changed (and OPIE set up, see below) at first login

Configuring OPIE for sudo access

Note: This section is not specific to jails, it applies to other machines accesses (eg, Ubuntu VM's) too. Ubuntu VM's use 'ortpasswd' (part of Orthrus) instead of 'opiepasswd'.

All users in the wheel group have sudo access. In order to use sudo, a user must configure OPIE by running 'opiepasswd' on the jail.

Using OPIE requires having an OPIE (S/Key) client on the local (trusted) machine. Some OPIE clients are:

At a high level the process is this:

  1. pick a good passphrase
  2. never expose it to the net
  3. run opiepasswd on the jail
  4. that will prompt you with an otp challenge
  5. take that challenge string and run it locally on your workstation
  6. enter your passphrase at the local prompt in 5
  7. repeat 5 and 6 until you are certain you entered your pw correctly
  8. paste the resulting six word response into the challenge prompt in 4
  9. have someone add you to the 'wheel' group
  10. run sudo
  11. that will prompt you for an otp challenge
  12. repeat 5-8
  13. get root

User configuration

[todo]

Software installed in Jails

See: http://tb.apache.org/index.php?action=list_buildports&build=9.0-RELENG-j-tlp-[$project]

Replace [$project] with the name of your project or visit http://tb.apache.org and navigate to your project.

Installing/Configuring Apache2

The Apache Installation can be found at /usr/local/etc/apache22/. The main data directory where you can publish any results/documentation/etc is located at /usr/local/www/apache22/data. The Apache instance can be controlled with the /usr/local/etc/rc.d/apache22 script (sudo access required) and the 'apache22_enable' /etc/rc.conf entry.

Installing/Configuring Java

Java - either OpenJDK and/or Oracles Sun JDK have been installed on some of the jails. See /usr/local/bin/java. If 'java -version' or 'which java' comes up empty ask infrastructure@ to install it for you or see the documentation if you fancy doing the license fetch/agree/install dance yourself.

See svn for extensive documentation

Is my VM puppet-ed?

Does /etc/puppet exist on the VM?