What is csoftadm?

This guide describes, using short examples, how to use our command-line configuration tool, csoftadm. The functionality provided by csoftadm (i.e., management of domains, e-mail configuration, databases, etc) is equivalent to that of our web-based control panel. It is also simple to use csoftadm from a script (for more details, see: Using csoftadm from a script).

To start csoftadm, log into your csoft.net account (if you are not familiar with SSH, see the documentation). At the shell prompt, enter the command:

  $ csoftadm

The csoftadm interface

A quick command reference is available from the Unix manual page of csoftadm:

  $ man csoftadm

Some help is also built into the command-line interface. Enter the "help" command to get a description of a command (or a category of commands):

  csoftadm> help
  csoftadm> help dns
  csoftadm> help mail
  csoftadm> help mail alias add

It is not necessary to remember the full syntax of commands when using csoftadm interactively. If any parameter is omitted, csoftadm will prompt (with the default values shown between brackets). Throughout this howto, italics denote user input. Since csoftadm implements context-sensitive command-line completion, the client will attempt to complete the typed command when the <TAB> key is hit (if there is a conflict, the possible entries are displayed).

  csoftadm> command
  question? default user input

An advantage of the command-line csoftadm over the web interface is the fact that commands may be scripted. The command-line argument " - " specifies to read one or more commands from the standard input. A command may also be passed using the " -c " argument:

  $ echo "mail alias add foo@bar.baz foo" | csoftadm -
  $ csoftadm -c "mail alias list" > myaliases.txt

E-mail Address Configuration

The mail alias commands permits the linking up of one or more recipients to an e-mail address. Possible types of recipients include a mailbox, an external e-mail address, a file on the server, a program (such as a mail filter) to execute on the server, or a reference to a previously-configured "rule set". Here are some examples.

1.1.Configure a new e-mail address

Have all messages addressed to user@example.com forwarded to joe@example.org:

  csoftadm> mail alias add
  E-mail address? user@example.com
  New recipient #1? [done] joe@example.org
  Added recipient `joe@example.org' to alias `user@example.com'.

Forward mail from bob@example.com to a new mailbox named bob:

  csoftadm> mail mbox add bob
  csoftadm> mail alias add bob@example.com bob

Deliver mail addressed to archive@example.com to an IMAP folder called MyArchive:

  csoftadm> mail alias add archive@example.com ./Mail/Maildir/.MyArchive/

Process messages to quote@example.com using a program located in ~/Mail/quote.pl.

  csoftadm> mail alias add quote@example.com |./Mail/quote.pl

We can combine the previous examples with conditions for message classification. For example, spam evaluates to the results of a SpamAssassin test on the incoming message. For convenience, delivery instructions may also be grouped into macros (such as &myInbox in the example below):

  # Filter spam to user@example.com into "Spam" folder:
  csoftadm> mail rule add user@example.com spam<=5.0 ./Mail/Maildir/
  csoftadm> mail rule add user@example.com spam>=5.0 ./Mail/Maildir/.Spam/
  
  # Create a new macro called &myInbox:
  csoftadm> mail rule add &myInbox spam<=5.0 ./Mail/Maildir/
  csoftadm> mail rule add &myInbox spam>=5.0 ./Mail/Maildir/.Spam/
  csoftadm> mail rule add &myInbox spam>=10.0 /dev/null
  csoftadm> mail rule add foo@example.com &myInbox
  csoftadm> mail rule add bar@example.com &myInbox
1.2.Deleting an e-mail address
Use mail alias del to remove an address:
  csoftadm> mail alias del
  Alias to delete? done joe@example.com
  Removed `joe@example.com' alias.
1.3.Display the current aliases

View the list of active aliases:

  csoftadm> mail alias list

Mailbox management

Mailboxes are dedicated accounts which are accessible via POP3/IMAP compatible mail clients, webmail or shell. Mailbox account users can also log into the Control Panel and perform certain management tasks (such as changing their password). The mail mbox add command creates a new mailbox. New mailboxes have no associated e-mail addresses by default (to create addresses, see mail alias add

2.1.Adding mailboxes

Use mail mbox add to create a new mailbox. You'll almost certainly want to use the IMAP format (the POP3 or "mbox" format is only intended for special applications, and mailboxes in IMAP format are actually accessible via POP3 as well).

  csoftadm> mail mbox add
  Name of new mailbox? mymailbox
  Password? mypassword
  Mailbox format? imap|pop3 imap
  Created `mymailbox' mailbox.
2.2.Changing mailbox passwords

Use mail mbox pass to change the password of a mailbox account:

  csoftadm> mail mbox pass
  name of mailbox? mymailbox
  new password? mypassword
  Changed password on "mymailbox" mailbox.
2.3.Deleting mailboxes

Delete a mailbox with the mail mbox del command:

  csoftadm> mail mbox del joe

List the current assortment of mailboxes associated with your account with mail mbox list:

  csoftadm> mail mbox list

DKIM key management

DKIM provides a method for cryptographically signing outgoing e-mail such that the domain part of the "From:" field can be validated by recipients. DKIM support is built into our mail system (DKIM keys are generated automatically as new domains are created), but you can also generate and manage them manually from csoftadm.

2.4.Managing DKIM signatures

Use mail dkim list to display your active DKIM keys, and mail dkim add to generate a new DKIM key:

  csoftadm> mail dkim list
  +-------------+----------+------------+---------------+
  | Domain      | Selector | Key Length | Last Modified |
  +-------------+----------+------------+---------------+
  | example.com | foo1     | 1024       | 12/2/2013     |
  | example.net | bar1     | 2048       | 6/10/2015     |
  +-------------+----------+------------+---------------+

  csoftadm> mail dkim add example.com baz 2048
  Added 2048-bit DKIM keypair to example.com (baz).
  
  csoftadm> mail dkim del example.com baz
  Remove DKIM keypair: example.com (baz).

Domain Name Management

The dns functions allow you to create, delete and manage domain names (and subdomains). Modifications will take up under 1 minute to propagate locally to the name servers in the cluster (globally, the propagation depends on the domain name's TTL settings).

3.1.Domain addition

Invoke dns add to initialize any new domain which is owned by you and for which the nameservers have been correctly delegated. To activate example.net (along with the standard www.example.net subdomain), you would use:

  csoftadm> dns add example.net
  Address [96.47.74.x]? (enter))
  Adding default records: MX SPF DKIM www.
  Created domain name: example.net (96.47.74.x)

The default address (96.47.74.x here) will cause the host to point to your csoft.net IP address. By default, this will enable web service for the domain. The standard web server will return the contents of ~/www/example.net/ in response to requests for http://example.net.

Note that an www.example.net alias is created by default. Similarly, the web server will handle requests for http://www.example.net by returning the contents of ~/www/www.example.net/ (which is usually going to be a symlink to ~/www/example.net).

Other IP addresses (IPv4 or IPv6) may also be used. Here, example.com would be pointed to a non-csoft.net IP address (and www.example.com added as an alias for example.com):

  csoftadm> dns add example.com 10.0.0.1
  csoftadm> dns add www.example.com @

Subdomains are configured the same way. Subdomains can point to IP addresses or other (possibly external) domains. If a subdomain should point to its parent domain, the shorthand @ may be used.

Activate a subdomain, nakht.example.net, using dns add. Assuming example.net points to an address local to the server, a directory would be created in ~/www/nakht.example.net.

  csoftadm> dns add nakht.example.net @

Create and link up another subdomain nebt.example.net to the IP address 10.0.0.2:

  csoftadm> dns add nebt.example.net 10.0.0.2

Domains can have more than one IPv4 or IPv6 address attributed to them. The dns ip and dns ip6 commands may be used to manage records with multiple addresses:

  csoftadm> dns ip add nebt.example.net 10.0.0.3
  csoftadm> dns ip del nebt.example.net 10.0.0.3
  csoftadm> dns ip6 add nebt.example.net 2001:db8:a0b:12f0::1
3.2.Domain deletion

Remove example.net off the DNS using dns del:

  csoftadm> dns del example.net
  Removed `example.net' host.
3.3.Managing mail exchangers (MX)

The DNS records for a domain may be adjusted to use a mail exchanger distinct from the one initially assigned to that domain. MX records have a priority, the MX with the lowest priority number is tried first. New MX hosts are added at the tail of the list using dns mx add.

To have mail for example.com served by mail.nekhbet.com, use the dns mx add command:

  csoftadm> dns mx add
  Domain/subdomain name? example.net
  Mail server hostname? mail123.csoft.net mail.nekhbet.com
  Added MX `mail.nekhbet.com' to host `example.net'.

To remove the MX record:

  csoftadm> dns mx del example.net mail.nekhbet.com
3.4.Managing name servers (NS)

The DNS records for a domain may be adjusted to use name server records distinct from the ones initially assigned to that domain, usually to accomodate a custom slave DNS setup. By default, at least two NS records are assigned per domain (the primary and secondary DNS of your server). Unlike MX records, NS records have no individual priority.

Use the dns ns command to manage NS records:

  csoftadm> dns ns add example.com ns123.example.com
  csoftadm> dns ns del example.com ns123.example.com
3.5.Managing the Start Of Authority (SOA)

The e-mail address listed by a SOA record for a domain may be modified with the dns soa command:

  csoftadm> dns soa example.net joe@example.net
3.6.Listing domain names

View the set of currently configured domain names with dns list. You can also display the DNS records in their entirety with dns zone:

  csoftadm> dns list
  example.com
  example.org
  * IPv4 address: 96.47.74.x
  * IPv4 reverse DNS: example.org

  csoftadm> dns zone example.com
  example.com {
              @    soa ns123.csoft.net. vedge.example.com.
	      @     ns ns123.csoft.net.
	      @     ns ns234.csoft.net.
	      @      a 96.47.74.x
	      @     mx 10 mail123.csoft.net.
	    www  cname @
  }
  * IPv4 address: 96.47.74.x
  * IPv4 reverse DNS: example.org

Note that most csoftadm "list" commands accept one or more arguments that correspond to search strings (exact vs substring matching is configurable with pref set exact-match).

  csoftadm> dns list pattern1 pattern2
  csoftadm> dns zone mydomain

Database management

The db commands are used to manage databases and their associated database users.

4.1.Creation of databases MySQL

The db mysql add command is called to create new MySQL databases. It does not create MySQL users by default, so you will have to grant privileges to one or more users later on with db mysql grant.

  csoftadm> db mysql add
  database name? exampledb
  Created database `exampledb'.
4.2.Destruction of databases

The db mysql del command will destroy a MySQL database. If needed, you can generate a backup of the database with the mysqldump(1) command.

  csoftadm> db mysql del exampledb
4.3.Database listing

The db mysql list command will show all databases that have been configured under your account, along with the associated MySQL users and their privileges. Alternatively, you can get a listing of your MySQL users and their privileges with db mysql userlist.

  csoftadm> db mysql list

  0. mydatabase {
      alice@localhost(SELECT,INSERT,UPDATE)
      bob@foo.domain.ext(SELECT)
  }
  1. myotherdatabase {
      alice@localhost(SELECT,INSERT,LOCK_TABLES,CREATE_VIEW)
      bob@foo.domain.ext(SELECT,SHOW_VIEW)
  }
  
  csoftadm> db mysql userlist

  0. alice@localhost {
      mydatabase: SELECT,INSERT,UPDATE
      myotherdatabase: SELECT,INSERT,LOCK_TABLES,CREATE_VIEW
  }
  1. bob@foo.domain.ext {
      mydatabase: SELECT
      myotherdatabase: SELECT,SHOW_VIEW
  }

4.4.Managing MySQL users

New MySQL users are created with the db mysql useradd command, and they are removed with db mysql userdel. When adding a user, you are asked for a hostname argument which limits connections from the given host (it is usually set to the default value of "localhost" unless direct remote access is needed).

  csoftadm> db mysql useradd
  database user name? myuser
  allow access from host? localhost (enter)
  password for myuser? secret
  password for myuser? (again) secret
  Created database user myuser@localhost.

  csoftadm> db mysql userdel myuser
  Deleted database user myuser.
4.5.Assigning privileges to MySQL users

In the following example, the MySQL user myuser is granted the permission to execute SELECT and INSERT queries on mydatabase. Note that any previously granted privileges on mydatabase will be revoked if they are not specified again.

To see all available MySQL privileges on your server, issue db mysql userprivs.

  csoftadm> db mysql grant
  database? mydatabase
  database user? myuser
  rights to grant? SELECT,INSERT,UPDATE,CREATE,... INSERT,SELECT
  Granted INSERT,SELECT rights to myuser user.
4.6.Database user password change

You can change the password for a MySQL user using db mysql pass.

  csoftadm> db mysql pass myuser
  new password? mypassword
  Changed password for myuser user.

Server-side configuration

Contained within this feature of csoftadm is the abilty to manipulate various elements in the settings of your account.

5.1.Showing configuration settings

Determine the precise scope of your control by bringing up the usage output and inspecting the available options:

  csoftadm> conf list
 0.          ssl (               no ) Enable SSL with custom certificate.
 1.         logs (              yes ) Apache access log enabled.
 2.       errlog (              yes ) Apache error log enabled.
 (...)

5.2.Changing a configuration setting

This command changes the value of a configuration parameter. The admissible values are peculiar to the specific parameter to be altered.

5.3.Registering SSL certificates

If your hosting package includes SSL support, you can use the ssl parameter to enable HTTPS service. See the SSL micro-howto for more details. It can take up to one hour for the new certificate to become effective.

In case the certificate, key or passphrase files in ~/ssl are incorrect, this parameter will automatically reset to off (and the error will be logged). The certificate's CN (Common Name) field must match the main domain name associated with your v-host (selected by the name setting).

  1. Create ~/ssl/ directory if needed (mode 0700).
  2. Place your certificate in ~/ssl/cert.
  3. Place your key in ~/ssl/key (mode 0600).
  4. Write your passphrase in ~/ssl/pp (if required, mode 0600).
  5. Set the ssl option to yes.

If the new certificate is not picked up within 1 minute, look for errors in your log (in /var/log/users/yourname). Errors in validating the certificate would appear in this logfile.

Client-side configuration

Some client-side csoftadm settings may be configured in ~/.csoftadmrc.

6.1.Show client-side settings

The pref show command lists the current client-side settings.

  csoftadm> pref show
      conf-descriptions = true
        db-default-host = "localhost"
      db-default-rights = "SELECT,INSERT,UPDATE,DELETE"
         dns-default-mx = "mail123.csoft.net"
         dns-default-ns = "ns123.csoft.net"
  (...)
6.2.Change client-side settings

The pref set command changes a setting local to the command-line csoftadm client.

  # Default address for new domains (IPv4)
  pref set dns-default-a 96.47.74.x
  
  # Default address for new domains (IPv6)
  # pref set dns-default-aaaa 2001:db8:a0b:12f0::1

  # Program used to display tables.
  pref set pager less

CVS account management

The cvs commands manage a group of sub-users who are restricted to CVS access, and must connect using the CVS_RSH=ssh method.

7.1.Add a CVS account

Use the cvs add command to create a new CVS account named mycvsuser:

  csoftadm> cvs add
  name of new cvs user? mycvsuser
  initial password? Vn4561
  Created `mycvsuser' cvs user.
7.2.Remove a CVS account

Use cvs del to delete mycvsuser:

  csoftadm> cvs del mycvsuser
7.3.Display active CVS accounts

Without arguments, cvs list displays all active cvs accounts:

  csoftadm> cvs list
  1.   anoncvs
  2.    yvonne
  3. mycvsuser
7.4.Changing CVS user passwords

Use the cvs pass command to change the password associated with a cvs account:

  csoftadm> cvs pass mycvsuser
  new password? Wasabi23
  Changed password for the `mycvsuser' cvs user.

Managing ssh public keys of CVS users

The cvs pubkey commands are used to manage the set of ssh(1) public keys associated with CVS accounts. Public key authentication allows CVS users to log in without having to enter their passwords.We recommend using ecdsa or ed25519 keys, preferably with a passphrase set (you can use ssh-agent(1) to achieve password-less authentication securely from your workstation).

7.5.1.Uploading ssh public keys

Paste the contents of your ssh public key file (such as ~/.ssh/id_dsa.pub) to cvs pubkey add:

  csoftadm> cvs pubkey add mycvsuser
  public key to add? ssh-dss AAAAB3NzaC1kc3MAAACBALhnPcOFZK ...
  Successfully added public key for `mycvsuser' user.
7.5.2.Displaying ssh public keys associated with a cvs user

Use the cvs pubkey list command to display the public keys used by mycvsuser:

  csoftadm> cvs pubkey list mycvsuser
  1. ssh-dss AAAAB3NzaC1kc3MAAACBALhnPcO9aFZKvrtXN/+cE+m ...
    
  1/32 public keys uploaded today.
7.5.3.Deleting public keys

To remove one of mycvsuser's public keys, use:

  csoftadm> cvs pubkey del mycvsuser
  public key to remove? ssh-dss AAAAB3NzaC1kc3MAAACBALhnPcO9aFZKtXN ...
  Successfully removed public key from `mycvsuser' user.

Subversion account management

The svn commands manage a group of sub-users who are restricted to Subversion access, and must connect using the "svn+ssh" protocol.

8.1.Add a Subversion account

Use the svn add command to create a new Subversion account named mysvnuser:

  csoftadm> svn add mysvnuser
  initial password? mypassword
  Created `mysvnuser' svn user.
8.2.Remove a Subversion account

Use svn del to delete mysvnuser:

  csoftadm> svn del mysvnuser
8.3.Display active Subversion accounts

Without arguments, svn list displays all active Subversion accounts:

  csoftadm> svn list
  1.    yvonne
  2. mysvnuser
8.4.Changing Subversion user passwords

Use the svn pass command to change the password associated with a Subversion account:

  csoftadm> svn pass mysvnuser
  new password? mypassword
  Changed password for the `mysvnuser' svn user.

Managing ssh public keys of Subversion users

The svn pubkey commands are used to manage the set of SSH public keys associated with Subversion accounts, to allow password-less authentication of Subversion users.We recommend using ecdsa or ed25519 keys, preferably with a passphrase set (you can use ssh-agent(1) to achieve password-less authentication securely from your workstation).

8.5.1.Uploading ssh public keys

Paste the contents of your ssh public key file (such as ~/.ssh/id_dsa.pub) to svn pubkey add:

  csoftadm> svn pubkey add mysvnuser
  public key to add? ssh-dss AAAAB3NzaC1kc3MAAACBALhnPcOFZK ...
  Successfully added public key for `mysvnuser' user.
8.5.2.Displaying ssh public keys associated with a Subversion user

Use the svn pubkey list command to display the public keys used by mysvnuser:

  csoftadm> svn pubkey list mysvnuser
  1. ssh-dss AAAAB3NzaC1kc3MAAACBALhnPcO9aFZKvrtXN/+cE+m ...
    
  1/32 public keys uploaded today.
8.5.3.Deleting public keys

To remove one of mysvnsuser's public keys, use:

  csoftadm> svn pubkey del mysvnuser
  public key to remove? ssh-dss AAAAB3NzaC1kc3MAAACBALhnPcO9aFZKtXN ...
  Successfully removed public key from `mysvnuser' user.

Billing Information

The billing functions allow you to update your contact information and billing preferences. Similar functionality is provided via the Control Panel.

9.0.Display and update current billing information
 csoftadm> billing status
 csoftadm> billing info
 csoftadm> billing update