Title: Zones 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]

# Zones for ASF projects # {#intro}

This document is a quick overview of Solaris 10's zones, intended for use
by ASF infrastructure to establish zones and for PMCs to manage their
zones.

Some quasi-helpful resources:

-  [blastwave.org - Solaris
Zones](http://www.blastwave.org/docs/Solaris-10-b51/DMC-0002/dmc-0002.html) 

-  [Sun BigAdmin Solaris Zones](http://www.sun.com/bigadmin/content/zones/) 

-  [Restricting Service Administration
blueprint](http://www.sun.com/blueprints/0605/819-2887.pdf) 

-  [Google](http://www.google.com/) : add the phrase "solaris 10" will get
docs.sun.com and forum.sun.com

# Solaris Newbies # {#newbies}

## TERM ## {#terminal}

Mac users will notice that the TERM setting xterm-color is not recognized.
Insead try vt100.
`
export TERM=vt100
` 

## PATH ## {#path}

The default PATH variable is set to just "/usr/bin" which is pretty
useless. Much of the good software is under /opt. Here is a good setting.
<pre>
export PATH=/sbin:\\
/bin:\\
/usr/sbin:\\
/usr/bin:\\
/usr/sfw/bin:\\
/usr/sfw/sbin:\\
/opt/sfw/bin:\\
/opt/sfw/sbin:\\
/opt/SUNWspro/bin:\\
/usr/ucb:\\
/usr/ccs/bin:\\
/opt/subversion-current/bin
</pre>

## .profile ## {#path}

Both of the above should be set in your ~/.profile file. Alternatively,
zone administrators can set this in the /etc/profile file, in which case it
will apply to all users.

# Zone management (instructions for PMCs) # {#management}

These are some notes to assist the PMCs to manage their zone.

See the other notes below for [creating and establishing
zones](#establish).

## Please document your zone to assist Infra management ## {#document}

Please add notes about your zone to the
https://svn.apache.org/repos/infra/infrastructure/trunk/docs/machines/helios/zones.txt
file (PMC name, root name and other maintainers, purpose, docs reference).
For examples, see the notes for other zones.

## Creating users in a zone ## {#useradd}

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

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

**Note:** Use of autohome is not recommended at this time

<pre>
As root,...

# useradd &lt;username&gt;

# passwd &lt;username&gt;

Note Solaris doesn't create the home dirs by default.
After creating the user, edit /etc/auto_home to have:

username&lt;tab character&gt;localhost:/export/home/username

[ place that line underneath the +auto_home line ]

Then, create the directory and run:

# mkdir -p /export/home/&lt;username&gt;

# chown &lt;username&gt; /export/home/&lt;username&gt;

Example auto_home entry:
jerenkrantz localhost:/export/home/jerenkrantz
</pre> 

## User configuration ## {#user}

Each user can now scp their SSH details to ${project}.zones.apache.org and
then do the usual initial configuration. See the [reference docs](#intro)
above. If you are not familiar with UNIX, then ask your PMC. You basically
need to chose your shell, add the profile and rc files, add your PATH and
some other environment variables and aliases.

If a newly added user does not have a password then the current
configuration of ssh will stop them from logging in via ssh, so every user
added will require a password. Once the user has their ssh public key
installed they will have no need for the password, but removing it will
likely prevent them logging in.

## Software installed in /opt ## {#software}

<pre>
sfw              -&gt; Sun Freeware [Companion CD]
SUNWspro         -&gt; Sun Studio 9. Recommended C/C++ compiler
elinks-0.9.3     -&gt; elinks text browser.
apr-1.1.1        -&gt; APR portability library
apr-util-1.1.2   -&gt; APR portability library
neon-0.24.7      -&gt; neon WebDAV client
subversion-1.1.4 -&gt; Subversion client
</pre>  <pre>
Other stuff...
/usr/java -&gt; 1.5
/usr/j2se -&gt; 1.4.2_06
</pre>

## Helios disk overview ## {#disk}

<pre>
/dev/dsk/c1t0d0s0 -&gt; mirrored array
/dev/dsk/c1t2d0s1 -&gt; /x1 [for now]

Metadb databases stored on:
/dev/dsk/c1t2d0s0
/dev/dsk/c1t3d0s0
/dev/dsk/c1t4d0s0

Mirrors stored on: [disabled, for now]
/dev/dsk/c1t3d0s1
/dev/dsk/c1t4d0s1
</pre>

## Setting up Apache2 as bundled with Solaris 10 ## {#apache2}

<pre>
Directories:
  /usr/apache2 - has the binaries etc.
  /etc/apache2 - has the configuration files.
  /var/apache2 - has the logs, htdocs, etc.

- login as root, cd to /etc/apache2.
- copy httpd.conf-example to httpd.conf 
  (and edit say the section for public_html, if you want to)
- Run:
  # mkdir /var/run/apache2
  (this allows httpd to write the pid file.)
  Note: It seems that a reboot cleans out /var/run so define it to be
  elsewhere.
- To check configuration
  # /usr/apache2/bin/apachectl configtest
- To start the server:
  # /usr/apache2/bin/apachectl -k start
- To stop the server:
  # /usr/apache2/bin/apachectl -k stop
- If you run into trouble check the logs
  under "/var/apache2/logs"

* You will need to also configure smf to automatically start services.
</pre>

## "Setting up SMF for Apache 2" ## {#apache2_smf}

This section describes how to enable SMF for the Apache 2 server service.
This is useful on zones as it negates the need to go through the usual
manual re-start procedure whenever the zone or zone server re-boots.

First, if it is running (which it more than likely is) we need to stop the
current Apache/2 HTTP service (provided by /etc/rc3.d/S50apache)

<pre>
/usr/apache2/bin/apachectl -k stop
Check it with 'ps -ef|grep httpd'
- If that doesn't work then :
'sudo pkill httpd'
</pre>

Second, Enable Apache 2 service provided by smf (svc:/network/http:apache2)

<pre>
svcadm clear svc:/network/http:apache2
svcadm enable svc:/network/http:apache2
Check the status with 'svcs -xv svc:/network/http:apache2'
Double check HTTP with 'ps -ef|grep httpd'
</pre>

Ok, so you should be up and running and relax with the knowledge that
Apache 2 and therefore your website will restart on its own should the
zone/server need a reboot

Not relaxed yet ? Lets test it - Try one of these methods :-

<pre>
1. Check the service is running with 'ps -ef | grep http'
   Stop the http service with 'pkill httpd'
   Check the service has automatically restarted with 'ps -ef | grep http'

2. Reboot the server with 'init 6'
   (wait a couple of minutes....)
   Check your zone website via %project%.zones.apache.org  - and/or -
   Check the service has automatically restarted with 'ps -ef | grep http'
</pre>

# Zone establishment (instructions for infrastructure) # {#establish}

This section assists the root people at ASF infrastructure to create
Solaris zones for certain PMCs.

See the other notes above for PMCs to [manage zones](#management).

## Creating a zone ## {#create}

The machine "helios" has Solaris zones.

The system on boot-up is in the 'global' zone. This is the master zone.

<pre>
# mkdir /x1/zones/&lt;zonename&gt;   [cannot be a symlink]

# chmod 700 /x1/zones/&lt;zonename&gt;

# zonecfg -z &lt;zonename&gt;
  create
  set zonepath=/x1/zones/&lt;zonename&gt;
  set autoboot=true (or autoboot=false)
  add inherit-pkg-dir
     [read-only path, will be lofs'd from global zone]
    set dir=/opt
    end
  add net
    set address=&lt;ip&gt; [helios IP range starts 140.211.11.66]
    set physical=bge0 [for a U5, it'll be hme0]
    end
  add dataset [if using ZFS storage]
    set name=zonestorage/&lt;zonename&gt;
    end
  commit
  exit

# zoneadm -z &lt;zonename&gt; install
['install' preps the zone.  It may take little while.]

# zoneadm -z &lt;zonename&gt; boot

# zlogin -C &lt;zonename&gt;
</pre>

On the initial boot, you will be prompted to configure the zone. Just like
you would for a 'blank' Solaris configuration. This is to get the
hostnames, root password, DNS settings, time zone, etc. So, as soon as you
boot the zone for the first time, connect via console!

(The recommended steps upon first-initialization are below.)

Also, see discussion of 'svcs'/'smf' for recommended services to disable.

## Configuring the zone on initial bootup ## {#initial}

<pre>
1. Select 'X Terminal Emulator' (xterms)    - option 12
...
2. Enter full hostname (i.e. &lt;zonename&gt;zones.apache.org)
[ Esc-2 can be used to advance these menus as well as F2. ]
[ Before this step, minotaur's named should have the name
  as a valid DNS entry ]
3. Do not configure Kerberos security (this is the default)
4. Select DNS for resolution (for now)

domain zones.apache.org
nameserver 140.211.166.130
nameserver 140.211.166.131
search apache.org zones.apache.org

5. Select GMT (timezone offset of 0)
   It is the bottom option; scroll down
6. Select a root passord
7. Select 'discover NFSv4 domain'
[ System reboots ]

8. Initialize local copy of sfw config files
    (to allow local sudoers)

# cp -rp /opt/sfw/etc.orig /etc/opt/sfw

9. Disable services (see below).

10. Done!

---
/etc/init.d/ is deprecated in favor of smf. 

To disable services:
svcadm disable network/smtp  [i.e. sendmail]

To enable services:
svcadm enable network/smtp  [i.e. sendmail]

To list running services:
svcs

Recommended list to disable
[cut-and-paste to your terminal]:
svcadm disable network/smtp
svcadm disable network/telnet
svcadm disable network/ftp
svcadm disable network/finger
svcadm disable network/login:rlogin
svcadm disable network/shell:default
svcadm disable application/x11/xfs
svcadm disable network/rpc/rstat
svcadm disable network/rpc/rusers
svcadm disable network/rpc/smserver
svcadm disable network/rpc/gss
svcadm disable network/rpc/rquota
svcadm disable network/rpc/cde-calendar-manager
svcadm disable network/rpc/cde-ttdbserver
svcadm disable network/nfs/client
svcadm disable network/nfs/cbd
svcadm disable network/nfs/mapid
svcadm disable network/nfs/status
svcadm disable network/nfs/nlockmgr
svcadm disable network/nfs/rquota
svcadm disable network/stdiscover
svcadm disable network/stlisten
svcadm disable network/cde-spc
svcadm disable network/rpc-100235_1/rpc_ticotsord
svcadm disable network/security/ktkt_warn

---
To keep up-to-date with system/security patches:
[ not necessary on zones; only on global zone ]

# smpatch update
</pre> 

## Helpful zone commands ## {#commands}

Helpful zone commands. Run from the 'global' zone aka helios.

<pre>
Listing all zones:
$ zoneadm list -vc

Booting a zone:

# zoneadm -z &lt;zonename&gt; boot

Logging into a zone as the console:

# zlogin -C &lt;zonename&gt;
[escape via ~. ;
remember to ~~ if you are connecting via SSH!]

Logging into a zone
[must be run as root; will connect as root of the zone]:

# zlogin &lt;zonename&gt;
[exit the zone by closing the shell]

Log into a zone as a specific user:

# zlogin -l &lt;username&gt; &lt;zonename&gt;

Shutting down a zone:

# zlogin

# shutdown -i5 -y -g0 [typical solaris shutdown command]

Rebooting a zone
[forcible reboot; bypasses shutdown scripts]:

# zoneadm -z &lt;zonename&gt; reboot

Removing a zone:

# zoneadm -z &lt;zone-to-zap&gt; uninstall

# zonecfg -z &lt;zone-to-zap&gt; delete
</pre>