Table of contents

  1. Registering for bundled support and backup services
  2. Contacting support
  3. Getting started
  4. Logging in for administration
  5. Accessing the main app
  6. Documentation and other helpful resources
  7. Why can't I login as root?
  8. Your voice counts: leave a review on the AWS Marketplace
  9. AWS Marketplace customer agreement
  10. What's new

Registering for bundled support and backup services

To provide the best user experience, each TurnKey solution on the AWS 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 if interested.
    • Unlimited Free "best effort" support via our public forums.

To benefit, sign up to the TurnKey Hub:

  1. Register for a Hub user account.
  2. Set up an IAMs role - second step of the Hub sign up process.
    • 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 info about the error.
  3. Important: Do NOT enter payment details - the third of the Hub sign up process.
  4. Instead, activate your AWSMP subscription by following the instructions here. Note that link will only work once your Hub account is created. If you have not already launched a server, please do that first. Then complete this final step.

For free "best effort" support via our forums:

Sign up for a free website user account. Website registration is separate to Hub registration. Ideally register with the same email address that you used for your Hub registration, but this is not necessary. Website account approval is a manual process and requires further action from you.

The fasted way to get your website account approved is contacting Hub support. Please note that you've made a website account and it needs approval.

Alternatively, guest post in the thread linked in the welcome email. Please note that you are an AWS Marketplace user. Guest posts also need manual approval to be published and expected approval time (for guest post and account approval) is generally within a few days, up to a week.

Contacting support

Web chat and ticketing system: the best way is to log into the Hub and click on the "Support" link in the top menu or via the blue chat icon, 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.

E-mail contact: <support AT>. This works best if you're already registered for support. If not already registered, please provide your AWS user ID number.

For fastest possible issue resolution, please provide as much info as possible regarding the problem. Including the specific appliance and version is useful, as well as any other relevant info. Providing the steps that led to the problem, including those that may seem irrelevant are very useful. Instructions on how to reproduce the issue are even better. Expected response time via the Hub or email are generally within one work day or less. Occasionally response times may be slightly longer - e.g. local public holidays.

Free unlimited "best effort" support via the forums: After your website account has been approved (as above), please start a new forum thread. Again for fastest resolution, please provide the same detailed info noted above for direct support. If you find a recent thread that exactly matches your situation you can reply there instead. Expected forum response times are generally within a few days. On rare occasions responses may take up to a week. Please feel free to bump a thread if you do not get a timely response.

Getting started

  1. Go to the AWS marketplace page of the TurnKey app you signed up
  2. Create an EC2 instance with 1-Click
  3. Point your browser at the public EC2 IP address for system initialization instructions:
    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
  4. Alternatively, go straight to the SSH login steps as noted below

System initialization in a nutshell

Simple interactive step-by-step system initialization process runs the first time you login with your SSH keypair to the admin account.

ssh admin@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.

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.

Unless you already have a Hub account, you can skip the Hub API step for backups for now. To create a Hub account, please see details above.

Once you have an activated Hub account, you can find your Hub API key on your Account Profile page (link towards the middle of the Hub's left hand menu). To add your Hub API key, log into your instance for administration as per below. If using Webmin to link, you should be greeted by the appropriate page. If logging in via SSH, run 'tklbam-init' and follow the prompts.

Read more: System initalization, configuration and preseeding

Logging in for administration

Every TurnKey solution on the AWS marketplace includes Webmin. Webmin is a web based administration UI. If you wish to use that, after initialization Webmin can be accessed via 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 port 12321 appended on the end - i.e.: ':12321'

Alternatively, if you are comfortable with CLI, you can continue to use that via SSH. Please note that Webmin also includes a Terminal client.

For further notes and info regarding your TurnKey appliance, please see the relevant page on our website. You will find a link to that on the AWS Marketplace page. Alternatively search via the box in the top right of this page - use the name and click the "app" radio button. A further option is to browse to the website front page and use the search there.

Accessing the main app

After system initialization is completed, the virtual fence is disabled, allowing you to securely access the local web server that was hidden behind the initialization instructions.

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


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 to HTTPS and if you were asked for a domain in the firstboot questions, your instance may redirect to the FQDN you provided.

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.

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 a Let's Encrypt. TurnKey Linux includes a Let's Encrypt integration be default, accessible via our Confconsole tool. Please see the Confconsole Let's Encrypt page for specific details.

Either way, you will need a FQDN (Fully Qualified Domain Name) that has the appropriate DNS records preconfigured to point to your server. For that to work consistently your appliance will either need an Elastic IP or a dynamic DNS service that updates your DNS records automatically when your IP changes.

Documentation and other helpful resources

Documentation and community resources:

  • TurnKey-specific documentation pages: All documentation pages and help resources on the TurnKey GNU/Linux website apply to AWS marketplace versions as well.

    The only AWS marketplace specific customization is that by default you don't login directly as root, but with the admin account instead.

  • Debian documentation: TurnKey GNU/Linux is essentially Debian GNU/Linux with batteries included. See Debian documentation for TurnKey GNU/Linux.

  • Ubuntu documentation: Since Ubuntu is closely based on Debian GNU/Linux most Ubuntu documentation may also be useful. Although please do not add an Ubuntu PPA apt repository, unless it is explicitly documented that it supports Debian. Adding Ubuntu PPAs may work fine initially, but will likely bite you down the track.

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.

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

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.

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 so the project's founders can thank you personally.

See also