====== Getting Started with a Joyent Accelerator ======
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 [[http://joyent.com/about/legal/accelerator-acceptable-use-policy|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:kb:faststart|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
====== Setting Up Your Domain Name (DNS) ======
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. It's best to do this yourself if you have access to a nameserver and your DNS zone file. Here is an [[shared:kb:default-dns-zone|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 [[http://www.isc.org/index.pl?/sw/bind/|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.
====== Hostname vs zonename and reverse record ======
- Run these commands at the shell prompt to find out:
- What is my hostname? hostname
- What is my zonename? zonename
- What is my IP? cat /etc/hosts
- 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). This is necessary if you want to send email from your accelerator ([[http://discuss.joyent.com/viewtopic.php?id=18997|forum post]]).
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. If this entry is missing then your email will be rejected (for example from Shared Accelerator hosted email account)
When submitting the ticket for any DNS related action please include the whois information which proves that you are the owner or technical contact for the name.
====== Changing your hostname ======
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).
- 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)
- reboot
- run at the command line: hostname your new name should display
- 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.
====== Running Webmin the first time ======
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 first time you start webmin you will see the following message "Virtualmin's configuration has not been checked since it was last updated. Click the button below to verify it now."
Select the pushbutton and Virtualmin will validate the settings
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
====== Create a Virtual Server ======
After the configuration check is complete, select **Create Virtual Server** from the menu on the left.
- Fill in the **New virtual server details** fields with:
- your domain name (example.joyeurs.com)
- a simple description
- administration password
- Administration username (example)
- Administration group (example)
- leave the rest of the settings at their default settings
- 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
===== Test out the site =====
- Point your browser to your newly created domain and see that the test page renders properly.
- Lets prove that it is indeed **your** site by making an edit to the index.html page
- ssh example@X.X.X.X and edit ~/web/public/index.html by adding Welcome to example.joyeurs.com
#svcs -a
- To stop a service svcadm disable NAME
- To restart a service svcadm enable NAME
- To to clear a service from maintenance svcadm clear NAME The service should then go offline and if all is well return to online.
- To see what services are in maintenance and why svcs -x
====== Sending root's email to a real user ======
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.
===== Postfix changes =====
- Run Virtualmin/Webmin.
- Select **webmin** link on the upper left
- Select Servers->Postfix on the left side
- Select General Options
- Internet Hostname of this Mail system set to **Default (provided by system)**
- Select Save and Apply
- Select Mail Aliases
- Select Create a new Alias at the bottom Address: root
Alias to: Email Address REAL_USERNAME
- Select save at the bottom
- Select Save and Apply above the list of aliases
You could also edit /opt/csw/etc/postfix/aliases and run the newaliases command
==== Trouble shooting ====
Check that tail -f /var/log/syslog is not showing any error messages
====== Setting Up E-mail ======
Managing a mail server is a significantly bigger undertaking than hosting a web site particularly when it comes to dealing with spam and the problems it causes. It is therefore **not recommended** that you run a mail server on your Accelerator. You are instead advised to use external services such as [[http://forum.joyent.com/viewtopic.php?id=9|Joyent's own Connector]] or Shared Hosting. Do this by [[http://discuss.joyent.com/viewtopic.php?id=21783|altering your A and MX DNS records]] (external to Joyent).
If, however, you do decide to run your own mail server, here are basic instructions to get started. This also AssUMes you have followed the instruction above. If you are jumping straight to this section, please review the earlier steps to make sure you are ready to enable email. Specifically renaming the hostname.
===== MX Record =====
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
**the full-stop (or period) after the domain name.** As MX records should not point directly at an IP address, we instead use a sub-domain which, in turn, points to your Accelerator's public IP. Once these changes to your DNS have propagated to servers, you should begin **receiving** mail on your Accelerator.
==== Testing it out ====
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.
===== Adding email users =====
To add accounts and aliases, use the [[shared:kb:users#adding-a-single-user|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.
===== POP Access =====
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.
===== IMAP Support =====
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
===== Courier service online =====
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.
===== Testing it out =====
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 [[http://discuss.joyent.com/viewforum.php?id=37|question here]]
==== POP3 ====
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.
==== POP3-SSL ====
From your local machine see that port 995 is responding correctly (A cert is returned):
openssl s_client -ssl3 -connect example.joyeurs.com:995
==== IMAP ====
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.
==== IMAP-SSL ====
From your local machine see that port 993 is responding correctly (A cert is returned):
openssl s_client -ssl3 -connect example.joyeurs.com:993
==== Trouble shooting ====
- 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=, 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.
====== Subversion ======
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 [[http://wiki.joyent.com/shared:kb:start#subversion|Getting Started with Subversion]]).
====== Securing Your Accelerator ======
Joyent recommend that you change your various passwords on your Accelerator; for instructions on how to do this, see [[accelerators:changingpasswords|Changing Passwords]] keep in mind the usual advice regarding the selection of strong passwords. This is the recommended methodapg -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 [[accelerators:ssh_public_key_only|Disable SSH Password Authentication]].)
- ''PasswordAuthentication''
- ''PAMAuthenticationViaKBDInt''
====== MySQL remote access ======
===== Enabling tunneling =====
- Edit /etc/ssh/sshd_config
- Change the following parameters to "Yes":
- AllowTcpForwarding yes
- GatewayPorts yes
- Restarting SSH:svcadm restart svc:/network/ssh:default
- Checking to ensure that SSH properly restarted:svcs -a | grep -i ssh
online 21:31:42 svc:/network/ssh:defaultThe "21:31:42" is the time at which it last changed state, in this case, the time at which we restarted it.
===== Remotely connecting =====
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 ([[ssh|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
====== Questions?? ======
Add any issues or questions on this guide here.