This guide is aimed at owners of Joyent’s 1/4GiB and 1/2GiB Accelerators who may not have a great wealth of sysadmin experience and wish to use their Accelerators much like Joyent’s Shared Hosting but with the extra level of control available. You are not limited to only using the stacks presented here. In fact, you have root access so you are free to do anything within the AUP. These instructions will also work on the Accelerator Pro (1GiB, 2GiB, ..., 32GiB). If you’re on a Facebook Accelerator (those with .fb.joyent.us in their hostnames), then you should follow the Facebook Quick Start instructions instead.

This guide attempts to describe setting up the following core functionality on an Accelerator as well as providing more general information for new users:

• Setting up your domain name
• Hosting a web site
• Hosting Subversion repositories
• Running a mail server

First things first: the 1/4GiB and 1/2GiB Accelerators come with a single dedicated public IP. However, you will almost certainly wish to use a domain name to refer to your Accelerator instead; to do so, you need to configure your DNS so that your domain will resolve to your IP. While it is apparently possible to get Joyent to do this for you on their name servers (e.g. dns1.joyentdns.com) by filing a ticket, it is better to do this yourself if you have access to a nameserver and your DNS zone file. Here is an example dns zone definition

Many domain registrars such as Gandi (http://www.gandi.net) offer the ability to use their nameservers and offer an interface to edit your DNS zone file to set up your domain. The following examples are based on the options provided by Gandi.

To establish the link between your domain name and public IP, you must specify what is known as an “A record”, this is done with the following two lines in BIND 9 format (for Gandi, these can be entered in their “Expert” interface):

domain.name. 3600 IN A 1.2.3.4
*.domain.name. 3600 IN A 1.2.3.4

Note the full-stop (or period) after your domain name. Make sure to replace domain.name with your own domain and 1.2.3.4 with your public IP. The 3600 is known as the Time To Live (TTL) and sets your A record to expire after 1 hour (3600 seconds) so that you can make changes and hopefully see it reflected online without too much delay.

The second line is known as a wildcard entry which ensures that anyone attempting to go to anything.domain.name will also be correctly resolved.

Note that those two lines may be abbreviated to the following:

@ 3600 IN A 1.2.3.4
* 3600 IN A 1.2.3.4

Do not worry as they are equivalent.

(See “Setting Up E-mail” below for information on MX records.)

Once enough time has passed for your changes to have been propagated to your ISP‘s DNS servers, you should be able to access your Accelerator via your domain rather than its IP.

1. Run these commands at the shell prompt to find out:
   1. What is my hostname?

      hostname

   2. What is my zonename?

      zonename

   3. What is my IP?

      more /etc/hosts

2. Out of the box your Accelerator will have its hostname set to an internal ID of the format zonename.textdrive.com. However, while this looks like a URL, visiting that address will not access your Accelerator.

Using the IP address to access the machine is fine, it is recommended that you change your hostname to one of your own choosing (example.com).

Joyent also provides SOMETHING.joyeurs.com such as example.joyeurs.com at no charge to you. Submit a ticket with your IP and desired domain name and the DNS entries will be created. If you are using a third party (recommended method) then you will need to submit a ticket so that the PTR record to allow reverse DNS lookups. (Joyent is the owner of the IP address and is the only one who may add the reverse entry.) This is important if you are going to be sending email from this server.

In the following files replace the zonename.textdrive.com with your new domain name (example.com, or example.joyeurs.com). Be very careful when editing these files. If your name has not be changed after the reboot, make sure that there are no extra spaces or lines (for example do not comment out things in /etc/nodename).

1. sudo nano /etc/nodename
   sudo nano /etc/hosts
   sudo nano /etc/inet/ipnodes

   (the last file might already be changed with the edit to hosts file)

2. reboot
3. run at the command line:

   hostname

   your new name should display

4. from another machine (local machine is fine) run

    host domain.tld

   where domain.tld is the answer from hostname in the previous step. That should return the IP in your welcome letter.

Log into Webmin with the details supplied in your Your Joyent Accelerator Is Ready email (this should be a URL similar to https://1.2.3.4:10000)

The status of your system is being checked to ensure that all enabled features are available, that the mail server is properly configured, and that quotas are active ..

      Mail server Postfix is installed and configured.
      Apache is installed.
      MySQL is installed and running.
      Plugin DAV Login is installed OK.
      Plugin SubVersion repositories is installed OK.
      Default IP address for virtual servers is X.X.X.X.
      Disk quotas have been disabled in the module configuration.
      All commands needed to create and restore backups are installed.

.. your system is ready for use by Virtualmin.

Updating all Webmin users with new settings..
.. done

After the configuration check is complete, select Create Virtual Server from the menu on the left.

1. Fill in the New virtual server details fields with:
   1. your domain name (example.joyeurs.com)
   2. a simple description
   3. administration password
   4. Administration username (example)
   5. Administration group (example)
2. leave the rest of the settings at their default settings
3. Select Create Server

You are now able to ssh in as example@X.X.X.X with the password entered in step 1.III.

 ssh example@X.X.X.X

You now have a /home/example directory which is looks very close to a Shared Accelerator.

 ls /home/example
Maildir      
cgi-bin      
etc          
homes        
logs         
php-fastcgi  
svn          
web

1. Point your browser to your newly created domain and see that the test page renders properly.
2. Lets prove that it is indeed your site by making an edit to the index.html page

   1.  ssh example@X.X.X.X

      and edit ~/web/public/index.html by adding

      <h1>Welcome to example.joyeurs.com</h1>

      in the <body> element.

3. Refresh your browser to see that indeed this is your site.

You are now ready to upload your customized content into the ~/web/public directory. Use your favorite SFTP application using your newly created domain name as the user. The IP of the accelerator for the host and the password you entered in step 1.III when creating the domain.

Depending on the framework you are using, you might need to see these instructions for further information on configuration details.

Thankfully, common technologies such as PHP5 and Subversion are already installed and configured and ready to use with web hosting so you should be able to serve PHP files from the start.

There are a couple of ways to check on what is running. See this guide for details about being reboot ready and what the various states mean.

Start Virtualmin from http:/X.X.X.X:10000/

1. Select Webmin on the upper left
2. Under System select Service Management Facility Configuration
   1. Any items which are in maintenance will appear at the top of the list
   2. Any items which are offline appear in yellow below the maintenance items and above the online items

1. To see a list of services

   #svcs -a

2. To stop a service

    svcadm disable NAME

3. To restart a service

    svcadm enable NAME

4. To to clear a service from maintenance

    svcadm clear NAME

   The service should then go offline and if all is well return to online.

5. To see what services are in maintenance and why

   svcs -X

root will get the output from the cron jobs and other system messages. It is recommended to change root’s email to be sent to a real user which is read on a regular basis.

1. Run Virtualmin/Webmin.
2. Select webmin link on the upper left
3. Select Servers→Postfix on the left side
   1. Select General Options
      1. Internet Hostname of this Mail system set to Default (provided by system)
      2. Select Save and Apply
   2. Select Mail Aliases
      1. Select Create a new Alias at the bottom

          Address: root
         Alias to: Email Address  REAL_USERNAME
         

      2. Select save at the bottom
      3. Select Save and Apply above the list of aliases

You could also edit /opt/csw/etc/postfix/aliases and run the newaliases command

Check that

tail -f /var/log/syslog

is not showing any error messages

In order for mail to be sent to your e-mail address(es) on your Accelerator, you will need to set up an MX record in your DNS zone file. You need to add the following lines (where domain.name is your domain and 1.2.3.4 is your Accelerator’s public IP):

domain.name. 1200 IN MX 10 mail.domain.name.
mail.domain.name. 1200 IN A 1.2.3.4

From your local machine make sure that the mail host is reported properly like so:

$host example.joyeurs.com
example.joyeurs.com has address 1.2.3.4
example.joyeurs.com mail is handled by 10 mail.example.joyeurs.com.

To add accounts and aliases, use the Virtualmin interface to do so. The only extra bit of work you need to do is to enable Courier so that you can use your mail client of choice to connect to your Accelerator’s mail server.

You will need to SSH into your machine and edit the /opt/csw/etc/courier-imap/pop3d file. You can do this with the following command:

sudo nano /opt/csw/etc/courier-imap/pop3d

Enter your admin password when you are prompted to do so. Then scroll down until you see the line near the bottom reading

POP3DSTART=NO

Change this line to read:

POP3DSTART=YES

and save the file by pressing Ctrl+O and then Ctrl+X.

You will need to SSH into your machine and edit the file /opt/csw/etc/courier-imap/imapd. Then scroll down until you see the line

 IMAPDSTART=NO

Change this line to read:

 IMAPDSTART=YES

The next step is to bring Courier service online with the following two commands (the order is important as the second depends on the first):

sudo svcadm enable svc:/application/cswcourier:authlib
sudo svcadm enable svc:/application/cswcourier:imap

You can then check to see that both of these are online by running

svcs -a | grep -i courier

to which you should get a response like the following:

online         21:22:58 svc:/application/cswcourier:authlib
online         21:35:49 svc:/application/cswcourier:imap

You should now be able to connect to your mail server from your mail client of choice.

In both cases you are looking for the OK. If you don’t get that then review the steps listed above. If you are still stuck, then google on the response to see what others have to say. If that still doesn’t work then post your question here

From your local machine see that port 110 is responding correctly:

$ telnet example.joyeurs.com 110
Trying 1.2.3.4...
Connected to example.joyeurs.com.
Escape character is '^]'.
+OK Hello there.
^]
telnet> Connection closed.

From your local machine see that port 995 is responding correctly (A cert is returned):

 openssl s_client  -ssl3  -connect example.joyeurs.com:995

From your local machine see that port 143 is responding correctly:

$ telnet example.joyeurs.com 143
Trying 1.2.3.4...
Connected to example.joyeurs.com.
Escape character is '^]'.
* OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION STARTTLS] Courier-IMAP ready. Copyright 1998-2005 Double Precision, Inc.  See COPYING for distribution information.
. logout
* BYE Courier-IMAP server shutting down
. OK LOGOUT completed
Connection closed by foreign host.

From your local machine see that port 993 is responding correctly (A cert is returned):

openssl s_client -ssl3 -connect example.joyeurs.com:993

1. Seeing errors like this in /var/log/syslog

   Oct 20 21:22:57 example.joyeurs.com postfix/smtp[2076]: [ID 197553 mail.info] 2E35E2F68: to=<linda@example.com>, relay=mail.example.com[8.12.37.104], delay=0, status=deferred (host mail.example.com[8.12.37.104] said: 450 4.7.1 Client host rejected: cannot find your reverse hostname, [8.12.36.201] (in reply to RCPT TO command))

   You need to submit a ticket requesting the PTR reverse record added. When it is correct then doing host domain.tld and the host X.X.X.X will correctly resolve as shown below

$ host example.joyeurs.com
example.joyeurs.com has address 8.12.36.201
example.joyeurs.com mail is handled by 10 mail.example.joyeurs.com.
$ host 8.12.36.201
201.36.12.8.in-addr.arpa domain name pointer example.joyeurs.com.

Set up your Subversion repositories using “SVN Repositories” under the “Services” menu of Virtualmin and grant repository access to users much as you would on Joyent Shared Hosting with “Edit Mail and FTP Users” (see Getting Started with Subversion).

Joyent recommend that you change your various passwords on your Accelerator; for instructions on how to do this, see Changing Passwords

apg -t -m 12 -M NCL

As you will be using SSH to access your Accelerator, it is also a good idea to take advantage of SSH‘s public key authentication instead of relying on using passwords. If you decide to rely on keys entirely and wish to disable password authentication.

Edit this file:

sudo nano /etc/ssh/sshd_config

Setting both of these values to no (More detail on Disable SSH Password Authentication.)

1. PasswordAuthentication
2. PAMAuthenticationViaKBDInt

1. Edit /etc/ssh/sshd_config
   1. Change the following parameters to “Yes”:
      1. AllowTcpForwarding yes
      2. GatewayPorts yes
2. Restarting SSH:

   svcadm restart svc:/network/ssh:default

3. Checking to ensure that SSH properly restarted:

   svcs -a | grep -i ssh
         online 21:31:42 svc:/network/ssh:default

   The “21:31:42” is the time at which it last changed state, in this case, the time at which we restarted it.

So you now are able to create a tunnel from your local machine to the remote machine. For example say you are on an OSX machine (see this guide for all platforms) then:

ssh -L3307:127.0.0.1:3306 -p 22 -N -t -x user@myhost.com

will create a tunnel from local port 3307 to remote port 3306 on myhost.com. The only thing you need to change in the user@myhost.com on the line above.

In another terminal you are able to connect to the remote mysql database.

mysql -u username -ppassword -h 127.0.0.1 -P 3307

Add any issues or questions on this guide here.