Title: FreeBSD Jails for ASF projects
Notice:    Licensed to the Apache Software Foundation (ASF) under one
           or more contributor license agreements.  See the NOTICE file
           distributed with this work for additional information
           regarding copyright ownership.  The ASF licenses this file
           to you under the Apache License, Version 2.0 (the
           "License"); you may not use this file except in compliance
           with the License.  You may obtain a copy of the License at
           .
             http://www.apache.org/licenses/LICENSE-2.0
           .
           Unless required by applicable law or agreed to in writing,
           software distributed under the License is distributed on an
           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
           KIND, either express or implied.  See the License for the
           specific language governing permissions and limitations
           under the License.

[TOC]

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](https://issues.apache.org/jira/browse/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 # {#useradd}

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

    :::shell
    $ 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 `sshusers` group

 - Key must be copied to /etc/ssh/ssh_keys

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

The `/root/bin/asf-sshkeys.sh` script is usually provided on our zones to help with this.

# Configuring OPIE for sudo access # {#opie}

**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:

- [Inner.net's OPIE](http://inner.net/pub/opie/) (Debian package [opie-client](http://packages.debian.org/opie-client)) **Note:** the package has been [removed from Debian](http://bugs.debian.org/511582).

- [SkeyCalc](http://www.orange-carb.org/SkeyCalc/) (Mac OS&nbsp;X)

- [Orthrus](http://code.google.com/p/orthrus/) (Unix-like; portable)

- FreeBSD: opiekey(1) is part of the base system

- [donkey](http://gitorious.org/donkey) (Debian package [donkey](http://packages.debian.org/stable/donkey))
  **Note:** Use the '-f' option to set the hash type, usually 'donkey -f md5' 

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 # {#user}

[todo]

# Software installed in Jails # {#software}

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 # {#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}

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](https://svn.apache.org/repos/infra/infrastructure/trunk/docs/FreeBSD_at_the_ASF/java.txt)
if you fancy doing the license fetch/agree/install dance yourself.

See svn for [extensive
documentation](https://svn.apache.org/repos/infra/infrastructure/trunk/docs/FreeBSD_at_the_ASF)