/ 
Mail-Toaster-5.54
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;
is_port_installed

Checks to see if a port is installed.

   $fbsd->is_port_installed( "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,

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,

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" )';
install_port
$fbsd->install_port( "openldap" );

That's it. Really. Well, OK, sometimes it can get a little more complex. install_port 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 openldap.

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

/usr/ports/net/openldap23-server
/usr/ports/net/openldap23-client
/usr/ports/net/openldap24-server
/usr/ports/net/openldap24-client

So, a full complement of settings could look like:

    $freebsd->install_port( "openldap-client",
		dir   => "openldap24-server",
		check => "openldap-client-2.4",
		flags => "NOPORTDOCS=true",
		fatal => 0,
	);

 arguments required:
   port - the name of the directory in which the port resides

 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

 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.

install_package
$fbsd->install_package( "maildrop" );

Suggested usage:

unless ( $fbsd->install_package( "maildrop" ) ) {
	$fbsd->install_port( "maildrop" );
};

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.

update_ports

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

   $fbsd->update_ports();

arguments required:
  conf - a hashref

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

conf_check
$fbsd->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.

AUTHOR

Matt Simerson <matt@tnpi.net>

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.net/computing/freebsd/

COPYRIGHT

Copyright 2003-2012, 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.