Zones for ASF projects

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:

Solaris Newbies

TERM

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

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.

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

.profile

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)

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

See the other notes below for creating and establishing zones.

Please document your zone to assist Infra management

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

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

As root,...

# useradd <username>

# passwd <username>

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

username<tab character>localhost:/export/home/username

[ place that line underneath the +auto_home line ]

Then, create the directory and run:

# mkdir -p /export/home/<username>

# chown <username> /export/home/<username>

Example auto_home entry:
jerenkrantz localhost:/export/home/jerenkrantz

User configuration

Each user can now scp their SSH details to ${project}.zones.apache.org and then do the usual initial configuration. See the reference docs 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

sfw              -> Sun Freeware [Companion CD]
SUNWspro         -> Sun Studio 9. Recommended C/C++ compiler
elinks-0.9.3     -> elinks text browser.
apr-1.1.1        -> APR portability library
apr-util-1.1.2   -> APR portability library
neon-0.24.7      -> neon WebDAV client
subversion-1.1.4 -> Subversion client

Other stuff...
/usr/java -> 1.5
/usr/j2se -> 1.4.2_06

Helios disk overview

/dev/dsk/c1t0d0s0 -> mirrored array
/dev/dsk/c1t2d0s1 -> /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

Setting up Apache2 as bundled with Solaris 10

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.

"Setting up SMF for Apache 2"

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)

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

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

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'

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

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'

Zone establishment (instructions for infrastructure)

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.

Creating a zone

The machine "helios" has Solaris zones.

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

# mkdir /x1/zones/<zonename>   [cannot be a symlink]

# chmod 700 /x1/zones/<zonename>

# zonecfg -z <zonename>
  create
  set zonepath=/x1/zones/<zonename>
  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=<ip> [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/<zonename>
    end
  commit
  exit

# zoneadm -z <zonename> install
['install' preps the zone.  It may take little while.]

# zoneadm -z <zonename> boot

# zlogin -C <zonename>

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

1. Select 'X Terminal Emulator' (xterms)    - option 12
...
2. Enter full hostname (i.e. <zonename>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

Helpful zone commands

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

Listing all zones:
$ zoneadm list -vc

Booting a zone:

# zoneadm -z <zonename> boot

Logging into a zone as the console:

# zlogin -C <zonename>
[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 <zonename>
[exit the zone by closing the shell]

Log into a zone as a specific user:

# zlogin -l <username> <zonename>

Shutting down a zone:

# zlogin

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

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

# zoneadm -z <zonename> reboot

Removing a zone:

# zoneadm -z <zone-to-zap> uninstall

# zonecfg -z <zone-to-zap> delete