subdomain
Create, edit, or delete a subdomain of a hosted domain (document root, redirect, web server configuration, and SSL)
- Command:
/go/subdomain - Category: Domains
- Required option:
--subdomain - Optional options:
--documentroot,--redirecturl,--action - Output: One status line
- Last updated: 2026-11-19
On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also
Overview
/go/subdomain manages the subdomains of a hosting account, such as blog.example.com under example.com. It can:
- create a subdomain: save it in the panel, build its Apache and Nginx configuration, and request an SSL certificate in the background
- edit a subdomain: change its document root and redirect URL
- delete a subdomain: remove its record and some of its configuration files
The subdomain name must have the hosted domain directly after its first label. For blog.example.com the parent domain is example.com.
snapshot uses this command to bring back the subdomains of a restored account.
Quick start
# Create a subdomain
/go/subdomain --subdomain blog.example.com
# Delete it
/go/subdomain --subdomain blog.example.com --action delete
Syntax
/go/subdomain --subdomain <name> [--documentroot <folder>] [--redirecturl <url>] [--action edit|delete]
| Form | Behavior |
|---|---|
--subdomain <name> |
Creates the subdomain. |
--subdomain <name> --action edit ... |
Changes its document root and redirect URL. |
--subdomain <name> --action delete |
Deletes it. |
Any --action other than edit or delete, including add, creates the subdomain.
[!WARNING] The command only works with the
--optionform. A plain/go/subdomain blog.example.comdoes nothing useful and printsubdomain already exists.
[!WARNING]
editoverwrites both values. A document root or redirect URL that you leave out is reset (the document root to the first part of the name, the redirect URL to empty). Pass both every time.
Options
| Option | Required | Default | Notes |
|---|---|---|---|
--subdomain |
Yes | — | The full name, such as blog.example.com. It must be shorter than 32 characters, and its parent domain must exist in /home. Names with more than one label before the parent, such as a.b.example.com, are not supported. |
--documentroot |
No | The first label of the name (blog) |
The folder the subdomain serves. How it maps to a folder on disk is decided by the web server configuration commands. |
--redirecturl |
No | Empty | A URL. The web server configuration commands use it for the subdomain. |
--action |
No | Create | edit or delete. Anything else creates. |
Any other option stops the command with Subdomain: Unknown parameter: <option>.
Output
| Outcome | What you get |
|---|---|
| Created | Subdomain "<name>" Created Successfully. This line is printed before the record is saved, and also when the subdomain already existed. |
| Edited | Modifying Subdomain <name>... |
| Deleted | Subdomain <name> has been deleted., then the output of reload. Exit code 1. |
| Unknown option | Subdomain: Unknown parameter: <option> and exit code 1. |
| Name too long | Invalid username <name> and exit code 1. The message says "username", but the limit applies to the whole subdomain name. |
| Parent domain missing | Domain <domain> does not exist. and exit code 1. |
A folder with that name exists in /home |
ubdomain <name> already exists. and exit code 1. The first letter is missing in the message. |
Logging
Every run is appended to /var/log/go/subdomain.log.
Examples
# Create a subdomain
/go/subdomain --subdomain blog.example.com
# Create it with its own document root
/go/subdomain --subdomain shop.example.com --documentroot shop-v2
# Create a subdomain that redirects
/go/subdomain --subdomain old.example.com --redirecturl https://example.com/new
# Edit: pass both values every time
/go/subdomain --subdomain shop.example.com --action edit --documentroot shop-v3 --redirecturl ""
# Delete
/go/subdomain --subdomain blog.example.com --action delete
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
ubdomain already exists. with an empty name |
The command was run without --subdomain. |
Use --subdomain <name>. |
Subdomain: Unknown parameter: ... |
A misspelled or unsupported option. | Use only the four options in Options. |
Invalid username ... |
The subdomain name has 32 characters or more. | Use a shorter name. |
Domain ... does not exist. |
The parent domain isn't hosted here, or the name has too many labels. | Check the name, and create the account with create. |
ubdomain ... already exists. with a name |
A hosted domain with exactly that name exists in /home. |
Choose another name. |
Created Successfully, but nothing changed |
The subdomain already existed, and the insert was ignored. | Use --action edit. |
| An edit removed the redirect or reset the document root | A value you didn't pass is replaced by its default. | Pass both --documentroot and --redirecturl. |
| A deleted subdomain still answers on Debian, Ubuntu, or Nginx | The delete step misses some configuration files. | Remove /etc/apache2/vhost/<name>.conf, /etc/apache2/vhost/<name>-le-ssl.conf, and /etc/nginx/vhost/<name>.conf by hand, then run reload. |
| The new subdomain doesn't open | The DNS record doesn't exist, or the web server hasn't reloaded. | Add the DNS record (the command doesn't), and run reload. |
| No SSL certificate | The certificate is requested in the background and needs the DNS record. | Fix DNS, then run ssl for the subdomain. |
| The files of a deleted subdomain are still on disk | The command never deletes files. | Remove the folder by hand if you want to. |
Exit code 1 after a delete |
By design. | Ignore the exit code for deletes. |
Details
What it does
- Logs the call, and reads the options. An unknown option stops the command.
- Splits the name: the first label is the directory, and the rest is the parent domain.
- Delete: removes the subdomain's record, removes
/etc/httpd/vhost/<name>.conf,/etc/httpd/vhost/<name>-le-ssl.conf, and/etc/nginx/vhost/<name>-le-ssl.conf, prints the message, runsreload, and exits with code1. - Create and edit: looks up the account's username, stops if the name is 32 characters or longer, and stops if
/home/<parent>doesn't exist. The document root defaults to the first label. - Edit: updates the document root and redirect URL in the panel.
- Create: stops if
/home/<name>exists. Otherwise prints the success message and inserts the record (ignored if it already exists). - Builds the web server configuration with
/go/apache-subdomainand/go/nginx-subdomain. - Requests the SSL certificate with
sslin a detachedscreensession.
flowchart TD
A["subdomain options"] --> B{"Action"}
B -- "delete" --> D["Remove record and some vhost files, reload, exit 1"]
B -- "edit or create" --> C["Check name length and parent domain"]
C --> E{"edit?"}
E -- "Yes" --> F["Update document root and redirect"]
E -- "No" --> G["Check /home/name, print success, insert record"]
F --> H["apache-subdomain, nginx-subdomain"]
G --> H
H --> I["Request SSL in background"]
Notes for maintainers
| Issue | Why it matters | Suggested fix |
|---|---|---|
The delete step removes only /etc/httpd/vhost/... (RPM systems) and Nginx's -le-ssl.conf file |
Deleted subdomains keep being served on Debian and Ubuntu, and by Nginx's plain .conf. |
Use the paths of the running system, or call the *-subdomain scripts with a delete action. |
The success message is printed before the insert, which uses INSERT OR IGNORE |
A duplicate prints success and changes nothing. | Check for an existing record and report it. |
edit overwrites unspecified values |
The redirect is cleared and the document root reset. | Update only the values that were passed. |
The plain form without -- is not supported |
Nothing is set, and the message is misleading. | Print usage, and require --subdomain. |
| The subdomain, document root, and redirect URL are not validated, and go into SQL and into file paths | ../ in the name changes which .conf file rm -rf removes, and quotes break the queries. |
Validate the name against ^[a-z0-9-]+(\.[a-z0-9-]+)+$, and the document root against a safe relative path without ... |
| The 32-character limit uses the wording "username" and applies to the full name | Probably copied from create, and DNS allows longer names. |
Fix the message, or drop the limit. |
Unknown --action values (including add) create |
A typo creates a subdomain. | Accept add, edit, and delete only. |
Only /home/<parent> is checked |
A folder that isn't an account gives an empty username. | Check that the parent is in the Site table. |
| Deleting doesn't check that the subdomain exists | A delete of a missing name prints success. | Report not found. |
| Create and edit don't reload the web server, and delete does | New configuration may not be active. Check whether the *-subdomain scripts reload. |
Reload in every path. |
SSL is requested in a detached screen without a DNS check |
Failures are invisible and not retried. Deleting doesn't remove the certificate. | Check DNS first, report the result, and remove the certificate on delete. |
| There is no PHP version option | The table has a PHPVersion column, but this command can't set it, so snapshot restores lose it. |
Add --phpversion. |
The log line is written without sudo, the Arguments variable is unused, and there is no root check |
Fails when not run as root. |
Re-run through sudo at the top, like most other commands. |
| Subdomains with more than one label are not supported | The parent is found by removing only the first label. | Find the longest hosted parent domain. |
See also
| Command | Description |
|---|---|
create |
Create a GoAdmio account from the command line |
alias |
Create an alias domain (parked domain) in GoAdmio |
primary |
Convert an addon domain to a primary domain |
ssl |
Install an SSL certificate for a domain in GoAdmio |
reload |
Reload PHP-FPM and the active web server |
directory |
Manage per-domain directory listings |
snapshot |
Restic-based per-domain snapshot backup and restore |