How to Create a Shell User in ISPConfig

This guide shows you how to create a shell user in the ISPConfig control panel so you can access a website's files over SSH. It is written for Noiz clients managing their own hosting account through ISPConfig. A shell user is sometimes called an SSH user or SSH account: it lets you log in to a command line on the server with an SSH client such as OpenSSH or PuTTY, and transfer files securely with an SFTP or SCP client such as WinSCP or FileZilla. You will also learn what the chroot option does and how to use an SSH key instead of a password.

Last reviewed: 27 July 2026, against ISPConfig 3.3.1p1. This guide is written for Noiz hosting and is kept current against ISPConfig. It complements, and does not replace, the official ISPConfig documentation linked below.

Official Documentation Reference

• How to Add a Website in ISPConfig (HowtoForge): the current field-by-field guide to the Sites module, including the shell user form, maintained by the ISPConfig developers' documentation site.
• ISPConfig Documentation overview: the index of all official ISPConfig documentation, including the full manual.
• How To Create and Install SSH Keys on the Shell (HowtoForge): generating an SSH key pair on Linux or macOS.
• Key-Based SSH Logins With PuTTY (HowtoForge): the tutorial the official manual recommends for generating and using SSH keys on Windows.

Prerequisites

• You can log in to the ISPConfig control panel.
• An existing website on your account. A shell user always belongs to one website; if you have not created one yet, see How to Create a Website in ISPConfig.
• A hosting plan that includes shell access. If the Command Line section or its Shell-User item is missing from the left menu, your plan's shell user allowance is zero and ISPConfig hides the section entirely.
• An SSH client on your computer. Linux, macOS and current versions of Windows include the ssh command in the terminal; on Windows you can also use PuTTY.

Open the Shell User Form

1. Log in to the ISPConfig control panel.
2. Click the Sites module in the top navigation.
3. In the left menu, under Command Line, click Shell-User. A list of any existing shell users on your account appears.
4. Click the Add new Shell-User button.

The shell user form opens on the Shell User tab. The same form has a second tab, Options, carrying the Web Username, Web Group, Shell and Base Dir settings, but ISPConfig shows that tab to administrators only. On a client login everything you need is on the Shell User tab, and those underlying values are derived from the website you choose.

Complete the Shell User Tab

Fill in the fields described below, then click Save. There is no server to pick on this form: ISPConfig creates the shell user on whichever server hosts the website you select in Site.

Site

In the Site drop-down, choose the website this shell user belongs to. The user's home directory is placed inside that website's directory tree, so the account can work with that site's files.

Username

In the Username field, enter the login name you want, for example deploy. ISPConfig shows a prefix next to the field and adds it to whatever you type, so the actual login name is the prefix plus your entry. For example, if the prefix shown is client1 and you type deploy, you will log in as client1deploy. Use the copy button beside the field to put the full name on your clipboard; you need it every time you connect. Only letters, numbers, full stops, hyphens and underscores are accepted, the name must be unique on the server, and the finished name including the prefix must not exceed 32 characters. A short list of system account names is reserved and will be refused.

Password

Type a password in the Password field and confirm it in Repeat Password, or click Generate Password to have ISPConfig create a strong one for you. The Password strength indicator rates your choice; use at least 8 characters, longer where you can, with a mix of upper and lower case letters, numbers and symbols, and avoid dictionary words, repeated or sequential characters, and anything drawn from names or personal details. This password protects command line access to your website's files, so treat it like an administrator credential. If you plan to log in only with an SSH key, still set a strong password here; you simply will not need to type it.

Chroot Shell

The Chroot Shell drop-down controls how much of the server's file system the shell user can see:

• Jailkit: the user is locked (chrooted, also called jailed) into the website's own directory tree, with a home directory of their own inside it. They cannot browse anything above that boundary, and can only run a limited, safe set of commands installed inside the jail. This is the recommended setting and is usually the standard on shared hosting.
• None: the user can browse the whole server file system, limited only by ordinary file permissions. The official manual flags this as a security risk, and on shared hosting it is normally not offered.

The choices shown depend on what your account allows; you may see only Jailkit. Select Jailkit unless Noiz has advised otherwise for a specific reason. The first time a jailed user is created for a website, the server builds the jail environment in the background, which can take a little longer than later changes.

Quota

The Quota field sets the maximum disk space, in megabytes, available to this shell user. A value of -1 means unlimited, which on a shared hosting account effectively means "up to my plan limit". Because the shell user works inside the website's directory, most people leave this at -1 and let the website's own quota apply.

SSH-RSA Public Key (for key-based logins)

The SSH-RSA Public Key (for key-based logins) field is optional. If you paste a public SSH key here, you can log in without typing a password: your SSH client proves your identity with the matching private key, which stays on your computer. Key-based logins are both more convenient and more secure than passwords, so they are worth setting up if you connect regularly. How to generate a key is covered in the next section.

Paste each public key on its own line, exactly as produced by your key generator: a single long line starting with the key type, for example ssh-rsa AAAA.... Despite the field's RSA label, the keys are installed as standard authorised keys on the server, so current OpenSSH key types are accepted; an RSA key is the safe choice if you are unsure. Never paste a private key into this field. Leave the field empty if you only want password logins.

Active

Leave the Active checkbox ticked so the account works as soon as it is created. Unticking it later disables SSH access for this user without deleting the account.

Save

1. Click Save. You return to the shell user list, where the new user now appears.
2. Watch for the small red change indicator near the top of the panel. It shows that ISPConfig is still creating the system account, and the jail if you chose Jailkit, in the background. Wait until it disappears before trying to log in; this normally takes under a minute.

Set Up Key-Based Logins (Optional)

To use the SSH-RSA Public Key field, you first need a key pair on your computer. On Linux, macOS or Windows (PowerShell or Command Prompt on current versions), open a terminal and run:

ssh-keygen -t rsa -b 4096

Accept the default file location, and optionally set a passphrase to protect the key file itself. This creates two files: a private key (id_rsa), which must never leave your computer, and a public key (id_rsa.pub). Display the public key with:

cat ~/.ssh/id_rsa.pub

Copy the whole output line, paste it into the SSH-RSA Public Key (for key-based logins) field of the shell user, and click Save. On Windows with PuTTY, generate the key pair with PuTTYgen instead and copy the public key text it displays; see the PuTTY tutorial in the documentation links above. Once the change indicator clears, your SSH client will log in without asking for the account password.

Connect via SSH

Once the change indicator has cleared, connect from your computer's terminal. Replace the example username and domain with your own details:

ssh [email protected]

Here client1deploy is an example of the full prefixed username and yourdomain.com is an example domain that points at your Noiz hosting server. The standard SSH port 22 is used unless Noiz has told you otherwise. The first time you connect, your SSH client asks you to confirm the server's fingerprint; type yes to continue, then enter the shell user's password if you are not using a key.

After logging in, a jailed user lands in their own home directory inside the website's jail and can move around the site's files. The jail's root is the website's base directory, so the site content sits at /web from the jailed user's point of view. Only a limited set of commands is available inside the jail; this is by design. The same username and password (or key) also work for secure file transfers with an SFTP client such as WinSCP or FileZilla using the SFTP protocol on port 22.

Troubleshooting

• Permission denied when logging in: check that you are using the full username including the prefix, for example client1deploy rather than deploy. Also confirm the Active box is ticked and that the red change indicator had cleared before you tried. Repeated failed attempts can temporarily block your internet address as a security measure, so pause a few minutes before retrying with the correct details.
• Key-based login still asks for a password: the public key was probably pasted incorrectly. Edit the shell user and check the field contains the complete key as one single line, starting with the key type such as ssh-rsa, with no line breaks inside it, and that it is the public key, not the private one. Save and wait for the change indicator to clear.
• Connection times out or is refused: check you are connecting to a domain that points at your Noiz hosting server, on port 22. Some office and public networks block outgoing SSH; try another connection if you suspect this.
• A command I need is missing inside the jail: jailed shells only include a limited command set. Open a support ticket stating which command you need and the Noiz support team will advise whether it can be made available.
• I cannot see files outside my home directory: this is the chroot jail working as intended. A jailed shell user can only ever see their own website's directory tree.
• The Shell-User menu item is missing: ISPConfig hides the whole Command Line section when the shell user allowance on your plan is zero, so shell access is not included. If the menu is there but opening the form reports that the maximum number of shell users is reached, you have used the allowance you do have. Open a support ticket either way to check it.

If you get stuck at any point, open a support ticket with the Noiz support team and include the shell username you created, the website it belongs to, and the exact error message your SSH client shows when you try to connect.