This guide is mostly aimed at advanced users, resellers, and developers who wish to use the more advanced interfaces provided by CsoftMGI.

Pipe to csoftadm

Commands can be fed to csoftadm(1) 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);

However, the MGID module provides a better interface (this is a Perl XS module with bindings to the libmgid library). The 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):

  #!/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/C++ client library libmgid provides the most efficient interface for issuing CsoftMGI queries. Programs using this library will establish a connection and speak directly with the 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 $2 }');
 
 # Uncomment the following for dsl on FreeBSD:
 # NEW_IP=$(ifconfig tun0 | awk '/inet/ { print $2 }');
 
 # Uncomment the following for dsl on Linux:
 # NEW_IP=$(ifconfig ppp0 | awk '/inet addr:/ { print $2 }' | 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