You are here
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.
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