/ 
Mail-Toaster-5.05
River stage zero No dependents
/ Mail::Toaster::FreeBSD

NAME

Mail::Toaster::FreeBSD - FreeBSD specific Mail::Toaster functions.

SYNOPSIS

Primarily functions for working with FreeBSD ports (updating, installing, configuring with custom options, etc) but also includes a suite of methods for FreeBSD managing jails.

DESCRIPTION

Usage examples for each subroutine are included.

SUBROUTINES

new
use Mail::Toaster::FreeBSD;
my $fbsd = Mail::Toaster::FreeBSD->new;
cvsup_select_host

Selects a host to cvsup port updates from. If you pass $conf to it, it will detect your country automatically. If fastest_cvsup is installed, it will detect it and use it to pick the fastest host in your country. If it is not installed and the hostname is set to "fastest", it will try to install fastest_cvsup from ports.

arguments optional:
   conf

result:
   a hostname to grab cvsup sources from
is_port_installed

Checks to see if a port is installed.

   $fbsd->is_port_installed( port=>"p5-CGI" );

arguments required
  port - the name of the port/package

arguments optional:
  alt - alternate package name. This can help as ports evolve and register themselves differently in the ports database.

result:
  0 - not installed
  1 - if installed
jail_create
   $fbsd->jail_create( );

arguments required:
   ip        - 10.0.1.1
   
arguments optional:
   hostname  - jail36.example.com,
   jail_home - /home/jail,
   debug

If hostname is not passed and reverse DNS is set up, it will be looked up. Otherwise, the hostname defaults to "jail".

jail_home defaults to "/home/jail".

Here's an example of how I use it:

ifconfig fxp0 inet alias 10.0.1.175/32

perl -e 'use Mail::Toaster::FreeBSD;  
     my $fbsd = Mail::Toaster::FreeBSD->new; 
     $fbsd->jail_create( ip=>"10.0.1.175" )';

After running $fbsd->jail_create, you need to set up the jail. At the very least, you need to:

1. set root password
2. create a user account
3. get remote root 
    a) use sudo (pkg_add -r sudo; visudo)
    b) add user to wheel group (vi /etc/group)
    c) modify /etc/ssh/sshd_config to permit root login
4. install perl (pkg_add -r perl)

Here's how I set up my jails:

pw useradd -n matt -d /home/matt -s /bin/tcsh -m -h 0
passwd root
pkg_add -r sudo rsync perl5.8
rehash; visudo
sh /etc/rc

Ssh into the jail from another terminal. Once successfully logged in with root privs, you can drop the initial shell and access the jail directly.

Read the jail man pages for more details. Read the perl code to see what else it does.

jail_delete

Delete a jail.

$freebsd->jail_delete( ip=>'10.0.1.160' );

This script unmounts the proc and dev filesystems and then nukes the jail directory.

It would be a good idea to shut down any processes in the jail first.

jail_start

Starts up a FreeBSD jail.

	$fbsd->jail_start( ip=>'10.0.1.1', hostname=>'jail03.example.com' );


 arguments required:
    ip        - 10.0.1.1,

 arguments optional:
    hostname  - jail36.example.com,
    jail_home - /home/jail,
    debug

If hostname is not passed and reverse DNS is set up, it will be looked up. Otherwise, the hostname defaults to "jail".

jail_home defaults to "/home/jail".

Here's an example of how I use it:

perl -e 'use Mail::Toaster::FreeBSD; 
  $fbsd = Mail::Toaster::FreeBSD->new;
  $fbsd->jail_start( ip=>"10.0.1.175" )';
port_install
$fbsd->port_install( port=>"openldap2", base=>"net" );

That's it. Really. Well, OK, sometimes it can get a little more complex. port_install checks first to determine if a port is already installed and if so, skips right on by. It is very intelligent that way. However, sometimes port maintainers do goofy things and we need to override settings that would normally work. A good example of this is currently openldap2.

If you want to install OpenLDAP 2, then you can install from any of:

/usr/ports/net/openldap2
/usr/ports/net/openldap20
/usr/ports/net/openldap21
/usr/ports/net/openldap22

So, a full complement of settings could look like:

    $freebsd->port_install(
		port  => "openldap2", 
		base  => "net",
		dir   => "openldap22",
		check => "openldap-2.2",
		flags => "NOPORTDOCS=true", 
		fatal => 0,
		debug => 1,
	);

 arguments required:
   port - the name of the directory in which the port resides
   base - the base or category the port is in (security, net, lang, etc.)

 arguments optional:
   dir   - overrides 'port' for the build directory
   check - what to test for to determine if the port is installed (see note #1)
   flags - comma separated list of arguments to pass when building
   fatal
   debug

 NOTES:

#1 - On rare occasion, a port will get installed as a name other than the ports name. Of course, that wreaks all sorts of havoc so when one of them nasties is found, you can optionally pass along a fourth parameter which can be used as the port installation name to check with.

package_install
$fbsd->package_install( port=>"ispell" );

Suggested usage:

unless ( $fbsd->package_install( port=>"ispell" ) ) {
	$fbsd->port_install( port=>"ispell", base=>"textproc" );
};

Installs the selected package from FreeBSD packages. If the first install fails, it will try again using an alternate FTP site (ftp2.freebsd.org). If that fails, it returns 0 (failure) so you know it failed and can try something else, like installing via ports.

If the package is registered in FreeBSD's package registry as another name and you want to check against that name (so it doesn't try installing a package that's already installed), instead, pass it along as alt.

arguments required:
   port - the name of the package to install

arguments optional:
   alt  - a name the package is registered in the ports tree as
   url  - a URL to fetch the package from

See the pkg_add man page for more details on using an alternate URL.

ports_check_age

Checks how long it's been since you've updated your ports tree. Since the ports tree can be a roaming target, by making sure it's current before installing ports we can increase the liklihood of success.

$fbsd->ports_check_age( days=>"20" );

That'll update the ports tree if it's been more than 20 days since it was last updated.

arguments required:
  days - how many days old it must be to trigger an update

arguments optional:
  url - where to fetch the cvsup-ports file.
ports_update

Updates the FreeBSD ports tree (/usr/ports/).

   $fbsd->ports_update(conf=>$conf);

arguments required:
  conf - a hashref

See the docs for toaster-watcher.conf for complete details.

rc_dot_conf_check
$fbsd->rc_dot_conf_check(check=>"snmpd_enable", line=>"snmpd_enable=\"YES\"");

The above example is for snmpd. This checks to verify that an snmpd_enable line exists in /etc/rc.conf. If it doesn't, then it will add it by appending the second argument to the file.

source_update

Updates the FreeBSD sources (/usr/src/) in preparation for building a fresh FreeBSD world.

   $fbsd->source_update( conf=>$conf);

arguments required:
    conf 

arguments optional:
    cvsup_server_preferred - 'fastest',
    cvsup_server_country   - 'us',
    cvsup_supfile_sources  - '/etc/cvsup-stable',
    fatal
    debug

See the docs for toaster-watcher.conf for complete details.

AUTHOR

Matt Simerson <matt@tnpi.biz>

BUGS

None known. Report any to author.

TODO

Needs more documentation.

SEE ALSO

The following are all man/perldoc pages:

Mail::Toaster 
Mail::Toaster::Conf
toaster.conf
toaster-watcher.conf

http://mail-toaster.org/
http://www.tnpi.biz/computing/freebsd/

COPYRIGHT

Copyright 2003-2006, The Network People, Inc. All Rights Reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of the The Network People, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.