Table of contents

  1. TurnKey AWS Marketplace bundled benefits
  2. Registering for bundled support and backup services
  3. Getting support
  4. Getting started with an AWS Marketplace server
  5. Administration of your server
  6. Accessing the main app
  7. Further information, documentation and other helpful resources
  8. Why can't I login as root?
  9. Your voice counts: leave a review on the AWS Marketplace
  10. Additional links

Bundled support and backup services details

To provide the best user experience, each TurnKey solution on the AWS MP (Marketplace) bundles the following services:

  1. Free 1-Click cloud backup, restore and migration: saves changes to files, databases and package management to encrypted storage which servers can be automatically restored from. See the TKLBAM doc page for more info.
  2. Chat and e-mail support for all default TurnKey components and configurations - all your questions, technical issues, arbitrary whims and desires, lovingly attended to by our dedicated staff of Jeremies. Including:
    • Unlimited Free initial "getting started" support and technical issues.
    • Unlimited Free Hub and TurnKey Linux questions.
    • One Free level 1 support incident per month.
      • If your issue is found to be a bug related to the default TurnKey configuration & components, the incident will not be counted.
    • Unlimited Discounted additional paid support - including adhoc break/fix support and major upgrades.
    • Unlimited Discounted support for customizations and custom development and support - within our expertise. Please ask us.
    • Unlimited Free "best effort" support via our public forums.

To access the bundled benefits, sign up the TurnKey Hub:

Register for bundled benefits

Accessing the bundled benefits that are included with your AWS Marketplace subscription require registration to the TurnKey Hub. Please carefully read these instructions before starting the registration process:

  1. Register for a Hub user account.
  2. Set up an IAMs role.
    • If you need more details re the IAMs role step, please see the IAMs role doc page.
    • If you still experience issues, please ask for assistance, providing screenshot(s) of the error.
  3. Important: When you reach the payment details step, do NOT enter payment details.
  4. Instead, activate your AWS MP subscription by following the instructions here. Note that link will only work once you have started the Hub registration process and your Hub account have been created. If you have not already launched a server, please do that first to complete this step.

Getting support

See below for the available support channels, but first please read about the fastest way to get your issue resolved:

Fastest issue resolution

No matter which channel your use to get support, ensure that you provide as much information as possible. To minimize back-and-forth and wasted time for all of us, please include these details:

  • Appliance name and version of your server.
    • If unsure, run turnkey-version in a terminal.
  • The server size/type and the region it is running in.
  • Details of the issue, including the specific symptoms.
  • All the steps you took prior to the issue occurring - even if they seem unrelated.
  • Instructions on how to reproduce the error/issue when possible. Providing these will ensure the fastest possible resolution.
  • Any log extracts you have. Please share as much as possible, at least the 10 lines above and below the specific error line(s).

Remember: there is no such thing as too much information when reporting a problem! I can filter out irrelevant details, but I can't read your mind! More information will mean faster resolution. :)

Web chat and ticketing system

The best and fasted way to access TurnKey support is via your TurnKey Hub account. Ensure that you are logged in, then click on the "Support" link in the top menu or the blue chat icon on the bottom left. If we're available we'll be able to chat with you in real-time, otherwise this will open an issue so we can get back to you ASAP. Generally response times are within one workday, although often quicker. Occasionally they may be slightly longer (e.g. public holidays).

E-mail contact

Send an email to support AT turnkeylinux.org. This works best if you're already registered with a Hub account and send the email from the same email address. If you're not registered, please be sure to note that you are using an AWS MP server and provide your AWS user ID number.

Free unlimited "best effort" support via our forums:

Sign up for a free website user account. Website registration is a separate process to Hub registration. If you have registered to the Hub, use the same email address. Website account approval is a manual process and requires further action from you.

The fasted way to get your website account approved is by TurnKey Hub support. In your message, please note that you've made a website account and it is ready for approval.

Alternatively, make a "hello" guest post on the forum thread linked to in the automated "welcome email" you will receive after website registration. In your "hello" guest post, please include that you are an AWS Marketplace user. Guest posts will not be visible until manually approved. Expected time frame for publishing your guest post and approving your account are generally a few days, up to a week.

Once your website has been approved, start a new forum thread. If you have found another thread that seems relevant, cross link to it. Expected forum response times are generally within a few days, up to a week. Please feel free to bump a thread if you do not get a timely response.

Getting started with AWS MP

If you have subscribed to a TurnKey AWS Marketplace product, you can launch an instance of it like this:

  1. Go to the AWS MP page of the TurnKey appliance you signed up for.
  2. Create an EC2 instance with 1-Click. AWS defaults should generally be fine but pay careful attention to these:
    • The keypair that you select for the instance - you will need local access to the related private key.
    • To ensure your server "just works", be sure to select the security group supplied by us.
    • Unless you have specific needs, accept the AWS defaults for network configuration, including VPC.
  3. Initialize your server:
    • Browse to the public EC2 IP address for instructions:
      http://ec2-public-ip-or-url/ - where 'ec2-public-ip-or-url is your instance's public IP, AWS DNS name or externally preconfigured DNS linked FQDN; or
    • Skip that step and log in via SSH, using the key pair you selected

System initialization

A simple interactive step-by-step system initialization process runs the first time you login. To access that, log into your 'admin' account via SSH. You will need to use the key you selected when creating the server.

System initialization is required to setup passwords, install security updates, and configure key applications settings. To avoid exposing an unprotected TurnKey system to a hostile Internet, a virtual fence redirects access attempts to potentially vulnerable services until you complete this step.

Logging in via SSH

To log in via SSH, you will need a SSH client installed on your local PC. The recommended client is OpenSSH. OpenSSH is the reference implementation of SSH. It should be pre-installed on all Linux and Mac PCs. Many newer versions of Windows will also have it installed, if not it can easily be installed. There are also alternative Windows SSH clients, such as PuTTY and WinSCP.

Using OpenSSH open a terminal and run this command:

ssh admin@ec2-public-ip-or-url

Where 'ec2-public-ip-or-url' is your instance public IP, AWS DNS name or a preconfigured FQDN (fully qualified domain name) via appropriate DNS records.

If you have multiple keys, then you may need to specificy the key to use, via the '-i' switch. E.g. (on Linux or Mac):

ssh -i /path/to/key admin@ec2-public-ip-or-url

Domain name

If you are asked to enter an FQDN during initialization, then ensure that it is a domain that points to your server. Please note that by default AWS servers will change their IP address when stopped and restarted. To workaround that limitation, you have a few options:

Registered domain - If you have or plan to get your own domain registered:

  • Use a "static IP" and appropriate DNS records:
    1. Attach an AWS Elastic IP (i.e. a "static IP") to your server. To link an Elastic IP to your server, please consult the AWS documentation.
    2. Create an "A" or "CNAME" DNS record pointing to that IP. To create DNS records, consult your registrar's relevant documentation.
  • Use a dynamic DNS client to update your DNS records when your IP changes:
    • If your domain is registered with AWS Route53, then the Hub has ability to control your DNS dynamically via the built in HubDNS tool. Requires Hub registration.
    • If your domain is registered with a third party registrar, then it may be possible to update the "A" or "CNAME" records via an alternate dynamic DNS client. To see if that is an option, then please contact your domain registrar and/or consult your registrar's relevant documentation.

No registered domain - If you don't want to have your own domain registered:

  • Get a free tklapp.com subdomain via the Hub. Your tklapp.com subdomain can be automated to update via the built in HubDNS tool. Requires Hub registration.
  • Get an alternate domain name from one of the various dynamic domain services and

Hub API key

If you have already signed up to the Hub, enter your Hub API key when asked. That will link your server's pre-installed backup tool to the Hub. You will find your key on the Hub's Account Profile page - click the "show" button to reveal it.

If you do not already have a Hub account, you can skip this step for now and initialize backups later. Once you have created your Hub account, you can initialize backups via terminal using tklbam-init. Alternatively, it can be done via Webmin - the built-in webUI admin panel.

To read more about initialization, visit the system initialization, configuration and preseeding documentation page.

Administration of your server

Webmin - Web based Administration user interface

Terminal initialization via SSH is always required. But after that you can use Webmin to administer your server. Webmin is visual web based administration UI (user interface) which is pre-installed in every TurnKey solution. Most, if not all administration tasks can be done via Webmin. Even if you find you do need to use the terminal occationally, Webmin includes a Terminal Module.

To access Webmin, in the address bar of your web browser, enter https://ec2-public-ip-or-url:12321 - where 'ec2-public-ip-or-url' is your instance public IP, AWS DNS name or externally preconfigured DNS linked FQDN. Note the port 12321 appended on the end - i.e.: ':12321'

Terminal

After initialization if you are comfortable with CLI (command line interface), you can continue to use that via SSH.

Accessing the main web application

After system initialization is completed, the virtual fence is disabled. Secure access to the main web application will be possible.

Point your browser to your EC2's instance public address: 

http://ec2-public-ip-or-url/

Where 'ec2-public-ip-or-url' is your instance public IP, AWS DNS name or externally preconfigured DNS linked FQDN.

Note that some appliances will auto redirect HTTP to HTTPS.

If you were asked to set a domain during initialization, your instance may redirect to the domain you provided. Please ensure that you have configured your domain first.

SSL/TLS browser warning

When accessing your appliance via HTTPS you will see a scary browser warning. Despite the warning, this is generally not a security issue when accessing your own site and you can click through the warning to access your site. Please do not ignore browser warnings when connecting to a third party site!

The reason for the browser warning is that browsers don't like self signed SSL/TLS certificates. Unfortunately, this is the only kind that can be generated automatically.

If you have configured a domain, you can eliminate the warning by replacing the random self signed certificate with a Certificate Authority signed SSL/TLS certificate. These can either be purchased from a trusted Certificate Authority or generated for free via Let's Encrypt. TurnKey Linux includes a Let's Encrypt integration via our Confconsole CLI tool. Access that by running 'confconsole' in a terminal - either SSH or the Webmin terminal.

Note that CA signed SSL/TLS certificates can not be generated for IP addresses, so you will need a domain configured.

Further information, documentation and other helpful resources

TurnKey appliance specific documentation

Every TurnKey server has a dedicated "appliance page" here on the website. That has notes and info specific to your TurnKey server. You will find a link to that on the AWS Marketplace page that you originally launched your server from. An alternate way to find your server's page is to use the search box in the top right above. Enter the appliance name in the text box, click the "App" radio button and hit enter. Another way to find the relevant appliance page is to search on the front page of the website. Use the alternate search box there, or scroll down to browse all the available options.

Appliance pages also have further links to documentation specifically relevant to your TurnKey appliance. Some links are for TurnKey specific documentation and usage. Others are external links with more documentation related to the pre-installed third party software.

General TurnKey documentation and community resources

There is a range of general TurnKey specific documentation, as well as general Linux, AWS and other relevant documentation:

  • TurnKey specific resources:

    All documentation and resources on the TurnKey GNU/Linux website apply to AWS marketplace versions as well. The primary exception is use of the 'admin' user account when logging in, instead of 'root'. The other is that some CLI commands may require root privileges. To gain root privileges when running as 'admin', prefix the command with the 'sudo'.
  • Debian documentation:

    TurnKey GNU/Linux is essentially Debian GNU/Linux with batteries included. TurnKey is binary compatible with Debian and each TurnKey major version is directly based on a Debian major version. Any tutorials and third party software instructions should work exactly as it would on Debian. We do tweak some default configuration and provide some some custom software, but otherwise Debian documentation is directly relevant. If you have something specific you wish to do and are unsure, please ask.
  • Ubuntu documentation:

    Ubuntu is also based on Debian GNU/Linux, so much of the Ubuntu documentation is also relevant. Ubuntu releases are not completely consistent with Debian releases, so some software may be slightly different versions and/or have slightly different default configuration.

    Important: Ubuntu is not binary compatible with Debian. That means that you should never install software using an Ubuntu PPA apt repository! It may work fine initially, but it will almost certainly come back to bite you down the track. The only exception is if the software provider explicitly states that their software supports Debian.

Why can't I login as root?

You can, you just need to enable this yourself:

admin@core ~$ sudo turnkey-sudoadmin off

This will safely disable the admin account and re-enable direct root access.

Will this make my system any less secure?

No. It'll just remove a small unnecessary hassle. For most single admin usage scenarios supported by TurnKey, administrating your system directly as root is no less (or more) secure than administrating it through an admin account with sudo root privileges. Using the root account for administration will reduce friction as most commands that you wish to run will require root privileges.

sudo is the Unix version of Simon Says:

Sorry Dave, I'm afraid I can't do that. You didn't say Simon Says...

So why not allow root logins by default?

We do everywhere else, but we have to make an exception on the AWS marketplace because its security policy doesn't permit vendors to allow direct access to the system root account:

Linux-based AMIs MUST lock/disable root login and allow only sudo access.

After unsuccessfully protesting this requirement we were forced to change the default TurnKey configuration (only on the AWS marketplace) so that instead of the root account an admin account with sudo root privileges is used.

Access to Webmin, the web based system control panel is unaffected. You just need to login with admin instead of root.

With shell access, the main difference is that you need to login as admin and that to execute commands as root you need to explicitly prepend them with the magic word "sudo":

admin@core ~$ sudo whoami
root

This doesn't really improve security. At best it might in some cases protect you from yourself.

It's kind of like if you're a James Bond villain with Tourettes. You don't want to accidentally start the self destruct sequence for your secret base so you train your henchmen not to take you seriously unless you first say Simon Says.

Some people believe strongly that doing things this way is always a good idea. Others find it silly and frustrating. Simon Says you decide.

Note: in multi-user scenarios, enforcing use of unprivileged accounts can be very useful. E.g. a sudo user can be limited to certain specific commands and their activities can be logged. Be aware though if no limitations are applied to a sudo user, then they can remove any user logging. As an aside, users on Linux desktop systems should always use a non-privileged account.

Your voice counts: leave a review on the AWS Marketplace

TurnKey is a work of love run by a small team of open source enthusiasts, not a big corporation with a sales team and marketing budget. We spend all of our resources developing TurnKey and improving the quality of service we provide.

That means we rely on users like you to spread the word and provide us with valuable feedback. Please consider leaving a review on the AWS Marketplace, and sending an e-mail to support AT turnkeylinux.org so the project's founders can thank you personally.

Additional links