One-Click Installation

ISPConfig 3.3 One-Click Installation

Overview

This guide takes you from a launched AWS instance to a working ISPConfig control panel. The installation is unattended and takes about three minutes. Before you start, check the minimum requirement.

Before you begin: Associate an AWS Elastic IP with your instance first. Without one, your public address changes whenever the instance is stopped and started, which breaks your domain and stops your SSL certificate renewing. An Elastic IP can only be assigned from the EC2 console, not from inside the instance.

Step 1: Connect to your instance

1. Launch the EC2 instance

• Recommended size: t3a.small or t3.small. The installer stops and tells you if the instance is too small.
• Open these inbound ports in the security group: 22, 80, 443, 8080, 8081, 21, 25, 587, 465, 110, 143, 993, 995, and 40110-40210 for FTP passive mode. The full table, with what each one is for, is on the Requirement page. Do not open 3306: the database is reachable only from inside the instance.

2. Connect over SSH

3. Run the installer

• Run it exactly as shown. You do not need to switch to the root user first.

• Do not run dnf update before the installer. The image ships as a tested set of packages, and changing them underneath the installer can leave it configuring versions it was not built against, including a running kernel that no longer matches the installed one. Patch the server in your own maintenance window after the installation has finished and you have signed in.
• Keep the terminal open until the installer finishes. It takes about three minutes.

Step 2: Save your credentials

• When the installer finishes it prints a summary containing your control panel username and password.

Write the password down before you close the terminal. It is generated uniquely for your instance and is not stored anywhere it can be read back. There is no recovery or reset tool, by design. If you lose it, the only remedy is to launch a fresh instance from the AMI and install again.

Step 3: Sign in to the control panel

• Open the address shown in the summary:

• Sign in with the username admin and the password from the summary.

Your browser will warn you, and that is expected

You will see “Your connection is not private”, or ERR_CERT_AUTHORITY_INVALID. Click Advanced and then proceed to <your-address> (unsafe) to sign in.

This is not a fault, and there are two separate reasons for it:

• You are browsing by IP address. No public certificate authority issues certificates for a bare IP address, so any panel reached at https://<ip>:8080/ will always warn.
• The server’s own hostname cannot be certified. A new AWS instance is named ec2-<ip>.compute-1.amazonaws.com. That domain is on the Public Suffix List, and Let’s Encrypt will not issue a certificate for a name under it. ISPConfig falls back to a self-signed certificate, which is what your browser is objecting to.

Adding a website with SSL does not remove this warning on its own. A website you create gets its own trusted certificate on port 443. The control panel on port 8080 keeps its self-signed one until you move it across. See Associating Your Domain, which is the step that removes the warning.

Set your server name before creating mailboxes

Your server starts with the Amazon hostname, something like ec2-3-231-146-94.compute-1.amazonaws.com. Receiving mail servers see that name when your server sends mail, and an Amazon hostname is a common reason for mail being treated as suspicious. Change it before you create any mailboxes.

• Go to System, then Server Config in the left menu, and stay on the Server tab.
• Find the Hostname field. It currently holds the Amazon name.
• Replace it with a fully qualified name of your own, then click Save.

What to enter, and what NOT to enter. Use a name dedicated to the server itself. It must be different from the domain you added as a website in Associating Your Domain.

Worked example. If you added ispconfig.example.com as your website in Associating Your Domain, do NOT enter ispconfig.example.com here. Enter a different fully qualified name on the same domain, such as server1.example.com or host1.example.com.

• server1.example.com
• host1.example.com

The point is that this name belongs to the machine itself, and is never a domain you will host websites or mailboxes for.

Do not use a domain you will host mail for. Saving this field also sets Postfix’s mydestination, which tells the server to treat that domain’s mail as local. If you later create mailboxes at the same domain, ISPConfig will manage them as virtual mailboxes while Postfix delivers to local system accounts instead, and mail to those addresses stops arriving. Keeping the server name on its own subdomain avoids the clash entirely.
Continuing the example: if the server name is ispconfig.example.com and you then create [email protected], that mailbox will accept the address and never receive anything. It reads as a mail fault, and the cause is this field.

Two things the name needs to be worth changing:

• An A record pointing that name at this instance’s public address, the same way you pointed your website domain.
• A matching reverse DNS record. Receiving mail servers check that your address resolves back to the name your server introduces itself with. On AWS this is set through the same Support Center request used to lift the port 25 restriction below, so it is worth asking for both at once.

Changing this field updates the system hostname, Postfix’s configuration and /etc/hosts, and restarts Postfix for you. Nothing further is needed on the command line.

Sending email from this server

AWS blocks outbound port 25 by default on all EC2 instances. Your server can receive mail immediately, but it cannot send to external addresses until you request removal of the restriction through the AWS Support Center. This is an AWS account setting and is not something the instance can change.

Where webmail, phpMyAdmin and shell accounts are

Three things customers ask for first are not on the control panel port. The control panel is on 8080; webmail and phpMyAdmin are served on 8081, which is where ISPConfig’s own buttons point.

Port 8081 must be open in your security group or neither webmail nor phpMyAdmin will load, and the panel’s own buttons for them will appear to do nothing. This is the most common cause of a blank or unreachable webmail page, and it is easy to hit if you attached a security group you already had rather than creating one from the Requirement page’s port list. The control panel on 8080 keeps working, so the server looks fine.

If webmail or phpMyAdmin do not load, check the security group before anything else. The same applies to the other services: mail will not arrive without 25, mail clients cannot send without 587, and FTP needs 21 together with the passive range 40110-40210.

Creating a mailbox, then reaching webmail

• In the panel go to Email > Domain and add your mail domain.
• Then Email > Email Mailbox and add a mailbox with a password.
• Open https://<your-domain>:8081/webmail and sign in with the full email address and that password.

Creating a database, then reaching phpMyAdmin

• In the panel go to Sites > Database and add a database. Create a database user at the same time.
• The database list has a phpMyAdmin button beside each entry, which opens https://<your-domain>:8081/phpmyadmin.
• Sign in with the database user you created, not with the database root account. Root is deliberately unreachable over the network and cannot be used here.

Creating a jailed SSH/SFTP account

Shell users are confined to their own directory, so one customer’s shell account cannot see another’s files or the rest of the server.

This is not a tab on the website. Go to Sites, then find the Command Line section in the left menu and click SSH/SFTP-User.

• Click Add new SSH/SFTP-User.
• Site: choose the website this account belongs to.
• Username: note the prefix shown beside the box. The account name is that prefix plus what you type, so it will not be exactly what you entered.
• SSH-RSA Public Key: paste the account holder’s public key. Use an ed25519 key: this field stops at 600 characters and a 4096 bit RSA key is longer than that. If they do not have one yet, they create it on their own machine with:

Then they read the public half, which is the part to paste. Never the file without .pub, which is the private key and must not leave their machine.

• Chroot Shell: set to Jailkit.
• Save, then wait about a minute. The jail is built by a background service, not at the moment you save.
• Open the SSH/SFTP-User list and read the final username from it, then connect.

Inside the session, ls / shows only that account’s own jail and /var/www does not exist, so one customer cannot reach another customer’s files.

The Password field does not grant SSH access on its own. This image ships with SSH password sign-in disabled, the way AWS images do. An account created with only a password will save successfully and will not be able to log in. Give the account an SSH key using the SSH-RSA Public Key field.

A shell user without Chroot Shell: Jailkit set is a normal system account with normal visibility of the server. Set it for every account you give to a customer.

DNS: BIND is installed, but not serving

BIND is installed and ISPConfig’s DNS manager works, so you can create and edit zones in the panel. The server does not answer DNS queries from the internet as shipped, and port 53 is closed. For most operators this is what you want: domains are usually pointed at a registrar’s or a provider’s nameservers, and an exposed DNS server is one more service to secure.

If you want to run your own nameservers, that has a few moving parts and a page of its own. See Setup Nameservers, which covers the two routes that work without a second instance and without glue records, and the approach to avoid.

Next step

Once you can sign in, continue to Associating Your Domain to put your own domain on the server and replace the certificate warning with a trusted certificate.