Scripting csoftadm
<-- Back to Documentation

This guide, aimed at advanced users, resellers and developers, describes the available methods of using csoftadm from a program or script.

Note

A special note regarding e-mail configuration: Scripting csoftadm makes it easy to create forwarders with multiple recipient addresses, but this should never be used to implement "mailing lists", for a number of reasons (e.g., no bounce checking is done for forwarders, users cannot unsubscribe, etc). Our mail system provides support for real mailing lists (via Mailman). The mailing list system is also scriptable and should be used instead of forwarders.

Using the csoftadm command

Commands may be piped to the csoftadm program using the the -c or - option. The following command dumps the list of e-mail addresses to a file:

  $ csoftadm -c "mail alias list" > aliases.txt

The - option reads commands from the standard input:

  $ echo "mail alias list" | csoftadm - > aliases.txt
Using perl

A perl script may call the csoftadm program in the following ways:

  open(CSOFTADM, '|csoftadm -') || die;
  print CSOFTADM qq{mail alias add "user@domain.ext" "insn"};
  close(CSOFTADM);
  my @aliases = `csoftadm -c "mail alias list"`;
  print @aliases, "\n";

The MGID module, however, provides a much more efficient interface than the csoftadm program ("mgid" is the name of the basic open-source package which csoftadm is based on). MGID is a Perl XS module for libmgid (the csoftadm C library). This module is documented in the MGID(3p) manual page. The following script authenticates and outputs the server announcements using the low-level query interface:

#!/usr/bin/perl
use MGID;
my $mgi = MGID->new('localhost', 73, $USERNAME, $PASSWORD)
    || die MGID::Error();
if ($mgi->ModuleAvail('Info')) {
	print $mgi-<QueryList('Info', 'Motd'), "\n";
}

The following script uses the high-level interface to mail configuration (see MGID::MailDeliveryCfg for details):

#!/usr/bin/perl
use MGID;
my $mgi = MGID->new('localhost', 73, $USERNAME, $PASSWORD)
    || die MGID::Error();
unless ($mgi->ModuleAvail('Alias')) {
	die MGID::Error();
}
# Print addresses
my $mailCfg = $mgi->MailDeliveryCfg();
foreach my $addr ($mailCfg->Addresses()) {
	print $addr->AddressUTF8()."\n";
	foreach my $insn ($addr->Insns()) {
		foreach my $cond ($insn->Conds()) {
			print "(if )".$cond->String()."\n";
		}
		print $insn->String()."\n";
	}
}
# Configure new address
my $addr = MGID::MailAddress->new('test-addr@domain.ext');
$addr->Add(MGID::MailInsn->newForward('dest1@domain.ext'));
$addr->Add(MGID::MailInsn->newForward('dest2@domain.ext'));
$addr->Commit($mgi) || die MGID::Error();
Using C/C++

The C library libmgid is the most efficient interface to csoftadm. Programs using this library will establish a connection and speak directly with the csoftadm server. C/C++ programs may be compiled with `mgid-config --cflags` and linked against `mgid-config --libs`. The API is documented in mgid(3).

Implementing DynDNS

The "dns edit" command may be used to update the address associated with a domain or subdomain. By calling csoftadm remotely, one can perform a DNS update every time a dynamic IP address is allocated to a router (e.g., by DHCP).

Before executing the script below, make sure that you have public key auth with ssh functioning (see the ssh howto). This script is best invoked from a dhclient script (typically /etc/dhclient-script depending on your dhclient installation), but it can also be invoked periodically (say every 4 hours) from a cron job.

 
 #!/bin/sh
 
 # This is a script for DynDNS. It finds a new IP, connects to the
 # server then the DNS commands in csoftadm are run, updating the A
 # record for a domain or sub-domain.
 
 # Uncomment the following for dsl on OpenBSD: 
 # NEW_IP=$(ifconfig pppoe0 | awk '/inet/ { print  }');
 
 # Uncomment the following for dsl on FreeBSD:
 # NEW_IP=$(ifconfig tun0 | awk '/inet/ { print  }');
 
 # Uncomment the following for dsl on Linux:
 # NEW_IP=$(ifconfig ppp0 | awk '/inet addr:/ { print  }' | cut -d":" -f2);
 
 # Uncomment the four commands below if you have no external interface 
 # on your computer; this is, if you are on a LAN. Install wget first. 
 # wget -nv http://bot.whatismyipaddress.com/ -O $HOME/.whatismyip
 # echo ' ' 
 # sleep 5 
 # NEW_IP=$(cat $HOME/.whatismyip);
 
 if [ ! -r $HOME/.old_IP ]; then
 	echo '1.2.3.4' > $HOME/.old_IP
 else
 	echo ' An old_IP was found.'
 	echo ' '
 fi 
 
 OLD_IP=$(cat $HOME/.old_IP);
 
 if [ $NEW_IP = $OLD_IP ]; then
  	echo ' Ugg! Same IP! Bailing out fast.'
	echo ' '	
	exit 1		
 fi
 
 # Below, replace "your_username@your_server.csoft.net" with the correct
 # entry and "home.domain.ext" with the domain pointing to your home
 # computer, which you want to resolve to its new IP.
 
 if [ $NEW_IP != $OLD_IP ]; then
 	echo ' Ah, a new IP was found. Here we go. The new IP is:' $NEW_IP
	echo ' '
	ssh your_username@your_server.csoft.net \
	    csoftadm -c "'dns edit home.domain.ext $NEW_IP'"
 fi
 if [ $? != 0 ]; then
	echo ' Failed!'
	echo ' '
	exit 1
else
        echo ' The DNS was successfully updated!'
        echo ' '
 fi
 
 if [ -r $HOME/.old_IP ]; then
	echo $NEW_IP > $HOME/.old_IP
 fi
 

This web site - © 2012 Csoft.net Hosting, Inc.
(Contact Us) (Privacy Policy)
  LPF Valid HTML 4.01 Transitional