Add "hosts" entry on your local PC

Context & Overview

Note that these instructions are relevant for any network connected device with a valid IP - not just TurnKey servers.

Some TurnKey Linux servers require a domain to be set. When that's the case, the main application (e.g. WordPress, Mediawiki, etc) will expect that the domain resolves to your server's IP address. However, sometimes you can't or don't want to use a publicly resolvable domain - i.e. a DNS record.

Adding a hosts file entry is one way to access a server via a domain name without actually needing to configure DNS records. When your PC attempts connection to a domain it reads the hosts file first. If the desired domain is found in the hosts file, the noted IP will be used.

Limitations

There are a number of limitations using a hosts entry to access your server by domain:

  • Each PC that you want to be able to access your TurnKey server from will need to have a hosts entry added.
  • Admin access to your local PC is required to edit the hosts file.
  • Server static IP is highly desirable - without a static IP, the hosts file will need to be updated every time your server IP changes.
That also means that entries in the hosts file will also override DNS records. So unless you want to block/override an external site that does have a DNS record, don't use an existing "real" domain name.

It's also worth explicitly noting if a domain matches a hosts entry, a DNS request will not be made. So unless you explicitly want to block/override a domain, only use site specific domains - not "real" ones. Otherwise, if you forget you made a hosts entry, troubleshooting a connection problem down the track may be a whole world of pain! E.g. a good site specific domain might be 'mediawiki.home.lan'; a bad domain would be 'mediawiki.turnkeylinux.org' (it doesn't exist but perhaps it might in the future).

Set static IP for server

Using a static IP for your server is not required, but as noted above, it is highly desirable. If you haven't already set on and want to, how you do that will depend on the platform that you are running TurnKey on:

Cloud AWS server - launched from the TurnKey Hub or AWS Marketplace

Add an "elastic IP" to your server via the AWS console. Do not set a static IP within the server itself - AWS servers should always get their IP from AWS DHCP!

LXC container - e.g. on Proxmox

It is recommended that the static server IP be set on the Proxmox host - not within the server itself. This is because by default Proxmox manages the LXC server's network config.

VM & bare metal

Confconsole (>> Advanced >> Networking), Webmin (https on port 12321) or manually via CLI.

Hosts file location

Windows

C:\Windows\System32\drivers\etc\hosts

Linux and MacOSX

/etc/hosts

Open hosts file for editing

First open the hosts file in your preferred text editor. Note that it must be a plain text editor. An editor that formats text - e.g. a word processor - will break your hosts file! To edit the file you must be an Administrator.

Windows

Windows Notepad is a common and sane option for editing plain text files.

Right-click on your text editor application (e.g. Notepad) and select "Run as administrator." Then either copy/paste "C:\Windows\System32\drivers\etc\hosts" in the address bar - or browse to that location via the text editors "Open" dialog box.

Linux & MacOSX

On 'nix systems (Linux, OSX, etc) it's often easiest to use your preferred CLI text editor within a terminal. Common CLI editors are nano, vim or emacs.

Launch your text editor in a terminal as a sudo user (or as root). E.g. using nano:

sudo nano /etc/hosts

Add new line to hosts file

Once you have opened the hosts file for editing, add a new line with a format like this:

<IP_ADDRESS> <DOMAIN_NAME>

E.g. to point 'mediawiki.home.lan' to IP address '192.168.1.100' - add a new line with this:

192.168.1.100 mediawiki.home.lan

Finally, save your updated hosts file and exit the text editor.

Test your domain

After adding your hosts entry, resolution of your domain to the specified IP should "just work". But to be sure, it's worth double checking via a terminal. So open a terminal (e.g. cmd.exe on Windows) and use ping. E.g.:

ping mediawiki.home.lan

If you get results noting the domain and the IP address of your server, then you are good to go. If it gives the wrong IP, then double check your hosts file. If it gives an error message, then double check that you can connect to the IP by pinging it. E.g.:

 ping 192.168.1.100

If that doesn't work, then double check that you have the IP of the server correct. Another thing to check is that networking (of your PC and/or your server) is configured correctly.

Final word

If you're happy with your domain, added it to your hosts file and can connect to your server, then that's pretty much it. All that is left is to enjoy your TurnKey server! :)

Update domain on TurnKey server

If you had already set the domain on your TurnKey server prior to reading this and would like to change it, you can do that by re-initializing the server. Obviously the domain in your hosts file will need to match the new domain.

If you have already started adding content/data to your server before re-initializing, do a backup first (e.g. TKLBAM) - just in case. We try to ensure that our initialization scripts are idempotent (i.e. can safely be rerun) but there may be an edge case we haven't considered. Please report any bugs or unexpected behavior via our forums or our consolidated issue tracker.

Re-initialization

You can use the 'turnkey-init' command to do a full re-initialization. That will include resetting the domain as well as all the other server config. You will need to answer all the initialization questions again, although it's fine to use the same as you did the first time (expect domain obviously):

turnkey-init

If you'd rather just re-initialize the main application to update the domain, you can run the application specific initialization script directly. The individual scripts are written in python with a .py file extension and located in /usr/lib/inithooks/bin. As a general rule, the name of application specific init script will match the application so can usually be guessed. If you would like to explictly check for the name, list all the files in the relevant directory:

ls -l /usr/lib/inithooks/bin/*.py

Then run the script using the full path. E.g. WordPress:

/usr/lib/inithooks/bin/wordpress.py