NAME

Mail::Toaster::FreeBSD

SYNOPSIS

FreeBSD scripting functions

DESCRIPTION

a group of frequently used functions for perl scripts running on FreeBSD systems.

Usage examples for each subroutine are included.

METHODS

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");

Input is two strings, first is the package name, second is an alternate package name. This is necessary as some ports evolve and register themselves differently in the ports database.

returns 1 if installed, 0 if not

jail_create

$fbsd->jail_create($input);

$input is a hashref as follows:

input = { 
    ip        => 10.0.1.1,
    hostname  => jail36.example.com,
    jail_home => /home/jail,
    debug     => 1
};

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

jail_home is optional, it 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 = new Mail::Toaster::FreeBSD; 
     $fbsd->jail_create( {ip=>"10.0.1.175"} )';

After running $bsd->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($input);

$input is a hashref as follows:

input = { 
    ip        => 10.0.1.1,
    hostname  => jail36.example.com,
    jail_home => /home/jail,
    debug     => 1
};

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

jail_home is optional, it defaults to "/home/jail".

Here's an example of how I use it:

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

package_install

$fbsd->package_install("ispell");

Suggested usage:

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

Installs the selected package from FreeBSD packages. If the first install fails, it'll 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 the second argument.

If you want to retrieve packages from a package site other than FreeBSD's (the default), then pass along that URL as the third argument. See the pkg_add man page for more details.

port_install

$fbsd->port_install("openldap2", "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's very intelligent that way. However, sometimes port maintainers do goofy things and we need to override the directory directory we install from. 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

BTW: The second argument ("net") is what determines where in FreeBSD's ports tree the script can find OpenLDAP. If you pass along a third argument, we'll use it instead of the port name as the port directory to install from.

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.

On yet other occassions, you'll want to pass make flags to the port. The fifth argument can be a comma separated list of make arguments.

The sixth optional flag is whether errors should be fatal or not. Binary values.

And the seventh is debugging. Setting will increase the amount of logging.

So, a full complement of settings could look like:

$fbsd->port_install("openldap2", "net", "openldap22", "openldap-2.2", "NOPORTDOCS", 0, 1);

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("20");

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

You can optionally pass along a URL as the second argument from where to fetch the cvsup-ports file. If you have a custom one for your site, pass along the URL (minus the file name).

ports_update

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

$fbsd->ports_update($conf);

$conf is a hashref. Optional settings to be passed are:

cvsup_server_preferred
cvsup_server_country
toaster_dl_site
toaster_dl_url

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

rc_dot_conf_check

$fbsd->rc_dot_conf_check("snmpd_enable", "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 is a hashref. Optional settings to be passed are:

$conf = {
    cvsup_server_preferred => 'fastest',
    cvsup_server_country   => 'us',
    toaster_dl_site        => 'http://www.tnpi.biz',
    toaster_dl_url         => '/internet/mail/toaster/',
    cvsup_supfile_sources  => '/etc/cvsup-stable',
 };

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.

COPYRIGHT

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.

To install Mail::Toaster, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mail::Toaster

CPAN shell

perl -MCPAN -e shell
install Mail::Toaster

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)