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, databases, etc) is equivalent to
that of our web-based
control panel, but it
is more easily automated and many users will prefer a command line
over a web interface.
Csoftadm's command-line interface
It is not necessary to remember the full syntax 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
Calling up the program
Log into your assigned csoft.net account (this is covered by the
documentation),
then at the shell prompt, issue "csoftadm".
$ csoftadm
To browse the online help, use the "help" command, optionally followed
by a command.
csoftadm> help
csoftadm> help dns
csoftadm> help mail
csoftadm> help mail alias
csoftadm> help mail mbox
csoftadm> help db
csoftadm> help conf
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 |
|
Forward all messages (including spam) for user@my-domain to
user@his-domain:
csoftadm> mail alias add
E-mail address? user@my-domain
New recipient #1? [done] user@his-domain
Added recipient `user@his-domain' to alias `user@my-domain'.
Forward mail from bob@my-domain to a new mailbox named bob:
csoftadm> mail mbox add bob
csoftadm> mail alias add bob@my-domain bob
Save mail sent to archive@my-domain into ./Mail/my-archive
(relative to your home directory):
csoftadm> mail alias add archive@my-domain ./Mail/my-archive
Process messages to quote@my-domain using a program located
in ~/bin/quote.
csoftadm> mail alias add quote@my-domain |./bin/quote
Note:
Please use this feature thoughtfully, keep in mind the possible floods of
messages that could be caused by spam or deliberate attacks to tie up
server resources.
If you want to process a large amount of mail, please
contact us about setting up a persistent LMTP server for this purpose.
We can combine the previous examples with conditionals to perform
classification of messages based on specific criteria.
In the following example, we use the "spam" conditional which allows us
to take decisions based on the results of a
SpamAssassin
test.
Groups of such instructions are referred to as "rulesets". For
convenience, rulesets can be configured independently of e-mail addresses.
csoftadm> mail rule add user@my-domain spam<=5.0 ./Mail/Mailbox.non-spam
csoftadm> mail rule add user@my-domain spam>=5.0 ./Mail/Mailbox.spam
csoftadm> mail rule add &myruleset spam<=5.0 ./Mail/Mailbox.non-spam
csoftadm> mail rule add &myruleset spam>=5.0 ./Mail/Mailbox.spam
csoftadm> mail rule add foo@my-domain &myruleset
csoftadm> mail rule add bar@my-domain &myruleset
|
|
1.2.
Deleting an e-mail address |
Use mail alias del to remove an address entirely:
csoftadm> mail alias del
Alias to delete? done myuser@my-domain
Removed `myuser@my-domain' 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 typically accessed via
POP3 or IMAP compatible mail programs. This command creates a new mailbox,
which is not associated to any e-mail address by default (see
mail alias add).
|
2.1.
Adding mailboxes |
|
Use mail mbox add to create a new mailbox:
csoftadm> mail mbox add
Name of new mailbox? mymailbox
initial password? mypassword
format? (pop3|imap) pop3
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 mymailbox
List the current assortment of mailboxes associated with your account
with mail mbox list:
csoftadm> mail mbox list
|
Domains and subdomains
The privilege of creating and modifying the DNS records belongs to those
subscribers who have purchased a
hosting package that includes an
unique IP address
(Budget v-host and upwards).
The purpose of the dns functions is to activate and configure domains and
subdomains. The domains, to be activated, must be registered to you and
arranged to use the proper nameservers.
The changes placed into the dns records do not take hold immediately.
As the alterations made to the dns radiate throughout the expanse of the
internet rather slowly, it will, in most cases, take approximately
4-8 hours for the domain to resolve on most nameservers.
|
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 sekhmet.net and create a www subdomain, you
would use -
csoftadm> dns add
domain/subdomain name? sekhmet.net
destination? 1.2.3.4 (enter))
Created `sekhmet.net' host.
csoftadm> dns add www.sekhmet.net @
Created `www.sekhmet.net' host.
Accepting the default destination will cause the host to point to your vhost
IP address (in this example, 1.2.3.4).
Therefore sekhmet.net would point to the ~/www/sekhmet.net
directory, and a symbolic link, ~/www/www.sekhmet.net, would be an
alias for this directory.
Alternately, an ip address may be explicitly specified as a domain's
destination. In this case, trektothecave.com will be pointed to an
ip external to csoft.net, with the www subdomain being an alias for
the latter -
csoftadm> dns add trektothecave.com 10.0.0.1
csoftadm> dns add www.trektothecave.com @
Subdomains are similarly configured, they can take an ip address as
a destination, or the character @ (meaning the origin, the parent
domain).
If the destination is an address local to the server (or it is "@" and
the origin's destination itself is local to the server), then a directory
is created in ~/www (except for subdomains named "www", which,
by default,cause a symbolic link to be created instead).
It is always possible to remove and create symbolic links and directories
in ~/www manually, using
ln(1) and
mkdir(1)
from your shell.
Activate a subdomain, nakht.sekhmet.net, using dns add.
Assuming sekhmet.net points to an address local to the server,
a directory would be created in ~/www/nakht.sekhmet.net.
csoftadm> dns add nakht.sekhmet.net @
Create and link up another subdomain nebt.sekhmet.net to the
IP address 10.0.0.2 -
csoftadm> dns add nebt.sekhmet.net 10.0.0.2
|
|
3.2.
Domain deletion |
|
Remove sekhmet.net off the DNS using dns del -
csoftadm> dns del sekhmet.net
Removed `sekhmet.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 sekhmet.com served by mail.nekhbet.com,
use the dns mx add command -
csoftadm> dns mx add
Domain/subdomain name? sekhmet.net
Mail server hostname? mail23.csoft.net mail.nekhbet.com
Added MX `mail.nekhbet.com' to host `sekhmet.net'.
Remove the MX record -
csoftadm> dns mx del sekhmet.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.
To assign sekhmet.com a NS record for ns.kheperw.com,
use the dns ns add command -
csoftadm> dns ns add sekhmet.com ns.kheperw.com
Remove the NS record with dns ns del -
csoftadm> dns ns del sekhmet.net ns.kheperw.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 sekhmet.net admin@sekmnet.net
|
|
3.6.
Listing domain names |
|
View the current array of domain names (not the subdomains) currently
configured with dns list. To display the sub-domains, the SOAs,
the MX and the NS records as well, use dns zone -
csoftadm> dns list
trektothecave.com
vedge.org
* IPv4 address: 1.2.3.4
* IPv4 reverse DNS: vedge.org
csoftadm> dns zone trek
trektothecave.com {
@ soa ns261.csoft.net. vedge.trektothecave.com.
@ ns ns261.csoft.net.
@ ns ns128.csoft.net.
@ a 1.2.3.4
@ mx 10 mail231.csoft.net.
www cname @
}
* IPv4 address: 1.2.3.4
* IPv4 reverse DNS: vedge.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? mydatabase
Created database `mydatabase'.
|
|
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 mydatabase
|
|
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).
-
Place your certificate in ~/ssl/cert.
-
Place your key in ~/ssl/key.
-
Write your passphrase in ~/ssl/pp (if applicable).
-
Set the ssl option to yes.
|
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 = "mail23.csoft.net"
dns-default-ns = "ns73.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.
pref set dns-default-a 10.0.0.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(1)
access, and must connect using the "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
public keys associated with CVS accounts, to allow password-less DSA/RSA
authentication of CVS users.
|
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 DSA/RSA authentication of Subversion users.
|
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 personal information
and billing detail.
|
9.2.
Display current billing information |
csoftadm> billing info
|
|
9.3.
Displaying the current status |
|
The billing status command displays the current status and service
level of your account.
csoftadm> billing status
Account status: ACTIVE
Service level: standard-vhost
|
|
