© 2024 CubeSoft Communications
All Rights Reserved.
All Rights Reserved.
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
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
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.
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 args"
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 ./Mail/Maildir/ csoftadm> mail rule add user@example.com spam>=5 ./Mail/Maildir/.Spam/ # Create a new macro called &myInbox: csoftadm> mail alias add &myInbox csoftadm> mail rule add &myInbox spam<=5 ./Mail/Maildir/ csoftadm> mail rule add &myInbox spam>=5 ./Mail/Maildir/.Spam/ csoftadm> mail rule add &myInbox spam>=10 /dev/null # The macro can now be referenced in addresses: csoftadm> mail alias add foo@example.com &myInbox csoftadm> mail rule add bar@example.com any &myInbox
csoftadm> mail alias del
Alias to delete? done joe@example.com Removed `joe@example.com' alias.
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
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.
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.
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 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.
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).
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).
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
Remove example.net off the DNS using dns del:
csoftadm> dns del example.net Removed `example.net' host.
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
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
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
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. hostmaster.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
The db commands are used to manage databases and their associated database users.
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'.
The db mysql del command will destroy a MySQL database. If needed, you can generate a backup of the database with the mysqldump command.
csoftadm> db mysql del exampledb
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
}
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.
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.
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.
Contained within this feature of csoftadm is the abilty to manipulate various elements in the settings of your account.
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. (...)
This command changes the value of a configuration parameter. The admissible values are peculiar to the specific parameter to be altered.
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).
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.
Some client-side csoftadm settings may be configured in ~/.csoftadmrc.
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"
(...)
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
The cvs commands manage a group of sub-users who are restricted to
CVS access, and must connect using the
CVS_RSH=ssh method.
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.
Without arguments, cvs list displays all active cvs accounts:
csoftadm> cvs list 1. anoncvs 2. yvonne 3. mycvsuser
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.
The cvs pubkey commands are used to manage the set of
ssh 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
to achieve password-less authentication securely from your workstation).
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.
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.
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.
The svn commands manage a group of sub-users who are restricted to Subversion access, and must connect using the "svn+ssh" protocol.
Use the svn add command to create a new Subversion account named mysvnuser:
csoftadm> svn add mysvnuser initial password? mypassword Created `mysvnuser' svn user.
Without arguments, svn list displays all active Subversion accounts:
csoftadm> svn list 1. yvonne 2. mysvnuser
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.
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
to achieve password-less authentication securely from your workstation).
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.
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.
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.
The billing functions allow you to update your contact information and billing preferences. Similar functionality is provided via the Control Panel.