Documentation-time logic

Document! But do not take this task as an addition to developing. Here is an example of an integrated way of developing and socumenting at the same time.

The example shows a script which includes its own documentation. With simple tools, we generate man documentation from its output.

First of all, you need this formatted output: --version and --help. This example applies the "fortunes" script written in a previous post.

[rodolfoap] /home/rodolfoap > fortunes --version
GNU fortunes v0.1

Copyright (C) 1999 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Written by Rodolfo Alcazar <rodolfoap@hotmail.com>
[rodolfoap] /home/rodolfoap > fortunes --help
GNU fortunes is a personal fortunes engine organizer, written in bash.

Usage: fortunes [OPTION]

Options:
-e edit fortunes file
-l enters learning mode
-m enters multiline-learning mode
--help shows this help
--version shows version

Examples:

fortunes --help shows this help
fortunes -e edits fortunes file
fortunes generates a random fortune
fortunes -l starts learning mode

Report bugs to rodolfoap@hotmail.com

Start documentation process:

[rodolfoap] /home/rodolfoap > help2man fortunes|gzip -f>fortunes.1.gz

User just access the man page. In this case, the man page is not stored in its proper location.

[rodolfoap] /home/rodolfoap > man ./fortunes.1.gz

Linux power tools and classic formats

This is an interesting one. I had a 200-pages book, and need a 50-page book, with 4 little pages on each page. So I based this script on psdim, one of a thousand linux power tools:
#bin/bash
IMAGES=4
echo Must have installed psdim!
echo Converting...
gs -dBATCH -dNOPAUSE -sDEVICE=pswrite -sOutputFile=$1.tmp.ps $1
echo PSDIM output --------------------
psdim -$IMAGES $1.tmp.ps
echo PSDIM output end ----------------
pstops $(psdim -$IMAGES $1.tmp.ps) $1.tmp.ps $1.tm2.ps
gs -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile=$1.tiled.pdf $1.tm2.ps
rm $1.tmp.ps $1.tm2.ps
rename .pdf.tiled.pdf .tiled.pdf $1.tiled.pdf
echo Done!

You just need to start exploring GNU power tools now!

Scripted Server Setup

As a tasks-overloaded systems administrator, I really experienced the information is, by far, the most important asset of a company motto. Enough to risk your job or your career if you lose some. So, years ago, I focused on two highlights on servers management: keeping safe data and automatizing administrative processes. I will focus on this article on the automatizing administrative processes issue.

With Turbolinux, I wrote once a script, which allows me, runt before a fresh install, to complete a mailserver setup. Install tooks 10 minutes. Script execution (install additional rpms, copying mailboxes from other server, replacing configuration files, configure services and reboot), 5 minutes. With bash.

The only problem was that next year we, the company, found ourselves working with SuSE. A couple of years, with Fedora. We expect the script will just need a little review with each scenario changing. False. The script needed a rewrite every time. So, as a part of writing automatization processes scripts, we include the "source code" of our needs.

This is an excerpt of a class I dictated. Useful for a mailserver setting up.

Linux Fedora Core 4 Server
==========================

- Install Fedora Core 4

- Do Not install SELINUX.

- Custom Type installation - no packages

- Hostname=www.example.org.bo

Firewalling config with IP Tables
=================================

Add this rules to /etc/sysconfig/iptables:
-A RH-Firewall-1-INPUT -p tcp --dport 22 -j ACCEPT
-A RH-Firewall-1-INPUT -p tcp --dport 25 -j ACCEPT
-A RH-Firewall-1-INPUT -p tcp --dport 80 -j ACCEPT
-A RH-Firewall-1-INPUT -p tcp --dport 110 -j ACCEPT

# service iptables restart

Create yum repository
=====================

Install createrepo with rpm:
# yum -y install createrepo

Create basedir:
# mkdir -p /rpm/Fedora/RPMS
# cd /rpm/Fedora/RPMS

Put each disc on cdrom and
# mount /media/cdrom; cp -v /media/cdrom/Fedora/RPMS/*.rpm . ; eject

On /etc/yum.repos.d/fedora.repo comment baseurl=, mirrorlist, gpg...,
and add
baseurl=file:///rpm/

Create repository:
# createrepo /rpm

Config Apache web server
========================

# yum -y install httpd
# service httpd start
# chkconfig httpd on

Config Pop3 server with Dovecot
===============================

# yum -y install dovecot
# service dovecot start
# chkconfig dovecot on

Config SMTP server with Sendmail
================================

# yum install sendmail-cf
# cd /etc/mail/

# vi sendmail.mc

Uncomment (wipe dnl):
dnl define(`confAUTH_OPTIONS', `A p')dnl
dnl TRUST_AUTH_MECH(`EXTERNAL DIGEST-MD5 CRAM-MD5 LOGIN PLAIN')dnl
dnl define(`confAUTH_MECHANISMS', `EXTERNAL GSSAPI DIGEST-MD5 CRAM-MD5
LOGIN PLAIN')dnl

Comment (put dnl):
DAEMON_OPTIONS(`Port=smtp,Addr=127.0.0.1, Name=MTA')dnl

Generate sendmail cf file:
# m4 sendmail.mc > sendmail.cf

Add domains served by server:
# echo example.org.bo >> local-host-names

Add the networks this server accepts mail from:
# echo 10.0.0 RELAY >> access

Regenerate hash tables by restarting service
# make
or
# service sendmail restart

Install a webmail server with SquirrelMail
=============================================

# yum install squirrelmail

Fill organizational data with
# /usr/share/squirrelmail/config/conf.pl
Must complete numbers 1 (general data), 7 (Motd) and 10 (languaje, here
we use es_ES)

Install Mailman mailing lists server
====================================

Install mailman:
# yum install mailman

Config mailman:
# cd /usr/lib/mailman/bin
# ./mmsitepass

Maybe this is not necessary, but we must know where it is:
# vi /etc/mailman/mm_cfg.py # put fqdn='www.example.org.bo'

Create lists
# ./newlist # create "mailman" list and copy generated aliases
to /etc/aliases
# ./newlist # create "mylist" list and copy generated aliases
to /etc/aliases
# ./mailmanctl start
# service sendmail restart
# service httpd restart
# service mailman start
# chkconfig mailman on

(on redhat, mailman require MAILMAN_USER and GROUP = 'root' on
Defaults.py)

You can see how easy is to "compile" this to bash, with kickfiles, sed, yum or apt.

Additional tip: whilst including this lines as comments on the script, include instructions if you are gonna execute interactive commands...