OpenPanel-CLI Administration Guide

From Openpanel Documentation Wiki
Jump to: navigation, search

Section last confirmed valid for OpenPanel-Cli release: 1.1.1.1 by AndrewLuecke.

OpenPanel-CLI is a text-based command line tool used for configuring OpenPanel. It is designed primarily for users who prefer fine-grained control over their server using a text interface and utilises similar commands to Cisco's CLI interface. It can also act as a "recovery" tool when an administrator is unable to access the GUI interface, or to reset password's when they are forgotten. To access the OpenPanel command line interface, type openpanel-cli or for a list of possible command line arguments, type openpanel-cli --help.

Please note, this document assumes that you are already familiar with most basic technical jargon and that you already understand the underlying concepts of server administration. If you aren't, we STRONGLY recommend that you read the OpenPanel-GUI Administration Guide first, as you may otherwise have trouble understanding the purpose of some commands.

Contents

Command Line Arguments

Section last confirmed valid for openpanel-cli release: 1.1.1.1 by AndrewLuecke.

root:~# openpanel-cli [[--help] | [--login | -l ] [--shellcmd|-c cmdstring]] [cmd] [cmd] [...]

--host, -h  
Connect to a destination OpenPanel host using TCP target port 4089. Authentication will always be required.
--shellcmd, -c  
Treats cmdstring like a shell-quoted list. This is primarily used for SSH sessions. An example of usage is:openpanel-cli -c "'configure domain example.net' 'show email'". Further information for system administrators on setting up SSH is available in the OpenPanel System Administration Guide.
--login, -l  
Authenticate based on username/password. When this parameter is not used, Openpanel-admin is the default username.
--help  
Display a list of available command line arguments which can be passed to OpenPanel-CLI.

Commands can be entered interactively in the shell, or non-interactively by entering them as command line arguments.

srv01:/# openpanel-cli "show firewall" version
.----------.---------.----------.
| id       | enabled | blockall |
|----------+---------+----------|
| firewall | true    | true     |
`----------^---------^----------'
OpenPanel CLI 1.1.1.1
2011-10-13T13:41:51 pbuilder@openpanel-builder.office.xl-is.net
Available under the GNU General Public License

Logging in

Section last confirmed valid for openpanel-cli release: 1.1.1.1 by AndrewLuecke.

After installing OpenPanel, you are able to login with the OpenPanel-CLI command. Without parameters, you are automatically logged in as openpanel-admin

root:~# openpanel-cli
 [openpanel]%

It is also possible to log in as a custom user by using the -L/--login parameter.

 openpanel-cli --login
 User Access Authentication
 Username: AndrewL
 Password:
 [openpanel]%

The default username created during install which accepts login is: openpanel-admin and the password is set by the admin during during installation. If you are unable to login, you may wish to try Resetting your password.

Basic Operations

Section last confirmed valid for OpenPanel-Cli release: 1.0.0 by AndrewLuecke.

The OpenPanel shell is similar in operation to the Cisco router iOS interface, where operations consist of commands, objects, fields and parameters.

Commands

Commands represent an action which is performed through the interface, and is always the first component of an action. A list of possible commands and their meaning is below:

configure Enter configuration for a specific object. Sets the context to a specified object.
 [openpanel]% configure domain hal9000.com
 [domain hal9000.com]% show
 .-------.-----------------.--------------.
 | Field | Value           | Description  |
 |-------+-----------------+--------------|
 | owner | openpanel-admin | Object owner |
 | id    | hal9000.com     | Domain name  |
 `-------^-----------------^--------------'
show Displays the fields and child objects within an object (current object or child object)
[domain hal9000.com]% show
.-------.-----------------.--------------.
| Field | Value           | Description  |
|-------+-----------------+--------------|
| owner | openpanel-admin | Object owner |
| id    | hal9000.com     | Domain name  |
`-------^-----------------^--------------'
[domain hal9000.com]% ..
[openpanel]% show domain hal9000.com
.-------.-----------------.--------------.
| Field | Value           | Description  |
|-------+-----------------+--------------|
| owner | openpanel-admin | Object owner |
| id    | hal9000.com     | Domain name  |
`-------^-----------------^--------------'

create Create a new object.
[openpanel]% create user testuser password="delete"  name_customer="Benny Hill" emailaddress="benny@hill.com"
% Object created with id: 79f0d5f1-5c4d-4b21-3308-ab565ec0cc4f 

If you require that the object is created with a different ownership object, use create as-user <USERNAME> <OBJECTTYPE> <OBJECTNAME>.

[openpanel]% create as-user dave domain hal9001.com
% Object created with id: 314807b5-2a18-41b1-56cf-a9c70637698c
% Owner set to dave
[openpanel]% show domain hal9001.com
.-------.-------------.--------------.
| Field | Value       | Description  |
|-------+-------------+--------------|
| owner | dave        | Object owner |
| id    | hal9001.com | Domain name  |
`-------^-------------^--------------'
set Modifies field(s) of current object
[openpanel]% configure user hal9000
[user hal9000]% set  address_zipcode="3111"
% Object updated
[user hal9000]% show
.-------------------.----------------------.------------------.
| Field             | Value                | Description      |
|-------------------+----------------------+------------------|
| owner             | openpanel-admin      | Object owner     |
| id                | hal9000              | Username         |
...
| address           |                      | Address          |
| address_zipcode   | 3111                 | Zipcode          |
| address_state     |                      | State / Province |
...
| comment           |                      | Notes            |
`-------------------^----------------------^------------------'
update Modifies an existing object's fields from outside the object
[openpanel]% update user hal9000 address_state="mars"
% Object updated
[openpanel]% show user hal9000
.-------------------.----------------------.------------------.
| Field             | Value                | Description      |
|-------------------+----------------------+------------------|
| owner             | openpanel-admin      | Object owner     |
| id                | hal9000              | Username         |
...
| address_zipcode   | 3111                 | Zipcode          |
| address_state     | mars                 | State / Province |
| address_city      |                      | City             |
...
| comment           |                      | Notes            |
`-------------------^----------------------^------------------'
password Preferred means of changing an objects password
[openpanel]% password user testuser
Enter new password: <ENTER PASS>
Retype new password: <REPEAT SAME PASS>
% Password updated
delete Delete an existing object. Keep in mind that deletes are recursive, and deleting an object will also remove all nested objects and objects which are owned by that object.
[openpanel]% delete user testuser
Do you really want to delete this item? [y/N] Yes
% Object 'testuser' removed
debug Debug. Used primarily by developers to assist in locating and fixing problems. Very few people have a need for this.
 
[openpanel]% debug params  firewall
<?xml version="1.0" encoding="UTF-8"?>
<dict>
        <dict id="enabled">
                <dict id="enabled">
                        <string id="description">Enabled</string>
                        <string id="type">bool</string>
                        <bool id="enabled">true</bool>
                        <bool id="visible">true</bool>
...
version Show current version
[openpanel]% version
OpenPanel CLI 1.0.1
2010-12-28T07:55:57 pbuilder@openpanel-builder.office.xl-is.net
Available under the GNU General Public License
exit (or .. or ^Z) Go up to parent object
[openpanel]% configure domain hal9000.com
[domain hal9000.com]% exit
[openpanel]%
- Go back to previous context
[openpanel]% configure domain hal9000.com
[domain hal9000.com]% configure masterdomain hal9000.com
[masterdomain hal9000.com]% end
[openpanel]% -
[masterdomain hal9000.com]%
end Go back to top level context
[openpanel]% configure domain hal9000.com
[domain hal9000.com]% configure masterdomain hal9000.com
[masterdomain hal9000.com]% end
[openpanel]%
quit Exit system
[domain hal9000.com]% quit
srv01:~#
help Brief help message
[openpanel]% help
Welcome to the openpanel cli shell.
Use the question mark key '?' to explore your command line.
For further information, see the openpanel-cli manpage.
[openpanel]%

The syntax for commands is generally in the form: command arguments param=value anotherparam="another value". Note how parameters that contain whitespace need to be enclosed by double quotes like above.

Objects

An Object is a container which can contain data and further objects. Navigation through the object tree is performed by executing the configure <object> <Deeper Objects ...> command to go deeper, and exit to return to a higher level. These commands are only possible on some objects.

 [openpanel]% configure user openpanel-admin
 [user openpanel-admin]% show
 .-------------------.-----------------------------.------------------.
 | Field             | Value                       | Description      |
 |-------------------+-----------------------------+------------------|
 | owner             | root                        | Object owner     |
 | id                | openpanel-admin             | Username         |
 | password          |                             | Password         |
 | name_customer     | Administrator               | Customer name    |
 | name_company      |                             | Company name     |
 | address           |                             | Address          |
 | address_zipcode   |                             | Zipcode          |
 | address_state     |                             | State / Province |
 | address_city      |                             | City             |
 | address_country   |                             | Country          |
 | telephone_country |                             | Phone            |
 | telephone_number  |                             | Number           |
 | fax_country       |                             | Fax              |
 | fax_number        |                             | Number           |
 | website           |                             | Website URL      |
 | emailaddress      | openpanel-admin@example.net | Email address    |
 | comment           |                             | Notes            |
 `-------------------^-----------------------------^------------------'
 [user openpanel-admin]% exit


The object tree has roughly the following overview:

 
 /
 - create domain
 - configure domain
    |- create email domain
    |- configure email
    |  |- create alias
    |  |- configure alias
    |  |   |- add destination
    |  |   |- update destination
    |  |   \- remove destination
    |  |- create address
    |  \- create box
 - create user
 - show opencore
 - create mysqldb
 - show network
 - update network

Help, Autocomplete and other key mappings

Inline help is supported by pressing the question mark ('?'). This help is contextual and will only display help-information relevent to your current context.

 [openpanel]% show ?
 user            System/OpenPanel user
 opencore        OpenCORE System Information
 prefs           System Preferences
 mysqldb         MySQL Database
 domain          A collection of domain-related services
 system-update   System software updates
 firewall        IPTables firewall configuration

Commands can also be completed automatically using the <TAB>-key. Auto-completion is supported for both commands and objects. For instance, typing show f<TAB> auto-completes the command to show firewall. If ambiguity exists, instead of auto-completing, a list of available options (similar to inline help) are shown instead. For instance:

 
 [openpanel]% s<TAB>
 show            Show current object or child objects
 set             Change field(s) of current object

The command line also follows many other standard terminal conventions. For reference, here is a list of key mappings (^ represents Ctrl):

^A Jump to start of the command line
^E Jump to end of the command line
^U Erase from beginning of line
^Y Erase until end of line
^F Next word
^B Previous word
<TAB> Complete word at previous position
? Show context-help for current position
^D Exit one level up (or exit shell if at root configuration level)
^Z Go back to root level
<more> When <more> is shown, <space> shows the rest of the list.

The best way to get to know your options is to use the '?' key liberally. Most commands are pretty explicit in what kind of arguments they expect. For some commands, the last row of arguments are written down as variable declarations in the following form: command arguments param=value anotherparam="another value". Note how parameters that contain whitespace need to be enclosed by double quotes like above. This is also the place where the question mark will yield an actual question mark in your input.

Users

Section last confirmed valid for OpenPanel-Cli release: 1.1.1.1 by AndrewLuecke.

Add user

Every object in opencore has an owner, so we first have to make a user to create objects "owned" by this user (don't be afraid to tab/questionmark around to get a feel for the other options): create user <name> password=<pwd> name_customer=<name> emailaddress=<emailaddress>

This will create user dave at the Acme Corporation and set his password:

 [openpanel]% create user dave password="tOps3kr1t" name_customer="David Windsock" name_company="Acme Corporation" emailaddress="dave@acme.org"

Viewing user details

We can check the details of this user:

 [openpanel]% configure user dave
 [user dave]% show
 .-------------------.------------------.------------------.
 | Field             | Value            | Description      |
 |-------------------+------------------+------------------|
 | owner             | openpanel-admin  | Object owner     |
 | id                | dave             | Username         |
 | password          |                  | Password         |
 | name_customer     | David Windsock   | Customer name    |
 | name_company      | Acme Corporation | Company name     |
 | address           |                  | Address          |
 | address_zipcode   |                  | Zipcode          |
 | address_state     |                  | State / Province |
 | address_city      |                  | City             |
 | address_country   |                  | Country          |
 | telephone_country |                  | Phone            |
 | telephone_number  |                  | Number           |
 | fax_country       |                  | Fax              |
 | fax_number        |                  | Number           |
 | website           |                  | Website URL      |
 | emailaddress      | dave@acme.org    | Email address    |
 | comment           |                  | Notes            |
 <more>

When a list is too big the text <more> is shown, which performs in a similar behaviour to the unix "more" command. Pressing space bar on your keyboard progressively will unveil the missing lines, line by line. Openpanel has been designed in this fashion to ensure that every line from large outputs in OpenPanel can be seen (without being scrolled upwards and removed from the screen).

Changing User Details

Changing the details for a user is done by setting the context to the user object (configure user <username>), and then typing set DETAIL_FIELD="what you want to set it as". An example is below:

 [openpanel]% configure user  test
 [user test]% set<TAB><TAB><TAB>
 password=*           Password
 name_customer=*      Customer name
 name_company=*       Company name
 address=*            Address
 address_zipcode=*    Zipcode
 address_state=*      State / Province
 address_city=*       City
 address_country=*    Country
 telephone_country=*  Phone
 telephone_number=*   Number
 fax_country=*        Fax
 fax_number=*         Number
 website=*            Website URL
 emailaddress=*       Email address
 comment=*            Notes
 [user test]% set  name_customer="Habbie the hutt"
 % Object updated
 [user test]% show
 .-------------------.------------------.------------------.
 | Field             | Value            | Description      |
 |-------------------+------------------+------------------|
 | owner             | openpanel-admin  | Object owner     |
 | id                | dave             | Username         |
 | password          |                  | Password         |
 | name_customer     | Habbie the hutt  | Customer name    |
 | name_company      | Acme Corporation | Company name     |
 | address           |                  | Address          |
 | address_zipcode   |                  | Zipcode          |
 | address_state     |                  | State / Province |
 | address_city      |                  | City             |
 | address_country   |                  | Country          |
 | telephone_country |                  | Phone            |
 | telephone_number  |                  | Number           |
 | fax_country       |                  | Fax              |
 | fax_number        |                  | Number           |
 | website           |                  | Website URL      |
 | emailaddress      | dave@acme.org    | Email address    |
 | comment           |                  | Notes            |
 `-------------------^------------------^------------------'

Resetting a password

Resetting a users password in OpenPanel is easy. The best way to change password is password user <USERNAME>.

 [openpanel]% password  user hal9000
 Enter new password:
 Retype new password:
 % Password updated

If you receive an error such as % No object created: (12294) The data for parameter 'password' does not match the required regexp, it means that the password isn't secure enough to be set as a password.

Another method of changing the password is by using [user test]% set password="NEW Password". We STRONGLY recommend against password modification using the set command though, as modifying the password in this fashion will expose the password in plaintext! When changing/setting a password, always use the password command instead!

Removing users

To remove users from OpenPanel, use delete user <id>. Always take care when removing users, as the operation is recursive, and all objects, domains and users owned by the user may also be deleted (without explicit warning). Below is an example of user removal:

 [openpanel]% delete user dave
 Do you really want to delete this item? [y/N] Yes
 % Object 'dave' removed

Domains

Section last confirmed valid for OpenPanel-Cli release: 1.0.0 by AndrewLuecke.

Please note
Please make sure beforehand that the authoritative DNS server directs to your server (ns record) for the domain you want to configure. To do so, use host included with the dnsutils apt package on Debian.
  $ host -t ns foo.com
  foo.com name server ns.foo.com.
Furthermore check that the applicable ports (DNS: 53, Webserver/vhost 80, FTP: 22)are not blocked by a firewall.

Creating a Domain

To create a domain (object), use create domain <domainname>. For example:

 [openpanel]% create domain foo.com
 % Object created with id: 0402641e-d05c-4516-225a-1c2c64347def

Please note that the domain owner is automatically set to the user which is performing the action. If you wish for the domain owner to be another user, use create as-user <USERNAME> domain <DOMAINNAME>. Later we can set certain limitations for that user (e.g. the user cannot create subdomains). For example:

 [openpanel]% create as-user dave domain daveshouse.org
 % Object created with id: 584804f3-7d02-4ff6-267e-0c586f4ce3b7
 % Owner set to dave
 [openpanel]%

Removing a Domain

Deleting domains is a recursive operation, so all child objects are deleted too (which includes email addresses, website vhosts, ftp accounts and DNS), so be careful when deleting a domain. To delete a domain, use delete DOMAINADDRESS.TLD. For eg:

 [openpanel]% delete domain  foo.com
 Do you really want to delete this item? [y/N] Yes
 % Object 'foo.com' removed


Viewing a list of domains

The easiest way to view a list of all domains visible to a user is to use show domain. If a list of all domains is required, you must login as openpanel-admin, as child users may only be able to see a subset of domains.

 [openpanel]% show domain
 .---------------------------.
 | id                        |
 |---------------------------|
 | $prototype$               |
 | example.org               |
 | openpanel.org             |
 `---------------------------'


Changing Domain Address

Unfortunately, the only means of changing a domain address at this time is to create another domain and replicate the settings for the domain which you wish to port. It is a manual operation currently!

Changing the domain Owner

Similar to changing a domain address, changing a domain owner at this time isn't possible. Admins are required to remove the domain and recreate it after logging in as the appropriate user.

Vhosts

Setting up vhosts

A vhost or web server is typically reachable at a www subdomain (e.g. www.foo.com).

For it to be reachable at this address somewhere the www.foo.com domain should point to this server. This can be by setting up a DNS server authoritative for the domain.

When a domain has been set up, we can create vhosts under it: create vhost <your-vhost-domain>

Create a vhost for www.foo.com (with admin user m@acme.org and mod_php installed):

 [openpanel]% configure domain foo.com                                                                        
 [domain foo.com]% create vhost www admin=m@acme.org mod_php=true
 % Object created with id: 6f72c4b2-faac-4b73-2a4e-becd647388cc
 [domain foo.com]% configure vhost www.foo.com
 [vhost www.foo.com]%

Create a ftp-user account to upload webcontent

 
 [vhost www.foo.com]% create ftp-user webmaster@www.foo.com password=test123
 % Object created with id: 3c012864-e09d-475c-c53e-605f058e2762


Forgot to set one of the options initially? Change settings like this later on.

 [domain foo.com]% configure vhost www.foo.com
 [vhost www.foo.com]% set ?
 admin=*         Email address of site admin
 mod_php=true    PHP
 mod_php=false   PHP
 mod_cgi=true    CGI
 mod_cgi=false   CGI
 [vhost www.foo.com]% set mod_php=false
 % Object updated


DNS

Section last confirmed valid for OpenPanel-Cli release: 1.0.0 by AndrewLuecke.

Setting up DNS

Before we can start we have to make sure the DNS is authoritative for the designated domain:

 dig +short +identify @foo.com
 f.root-servers.net. from server 19.170.88.100 in 23 ms.

Where 19.170.88.100 is the host we run the DNS server on. On Debian, dig is part of the dnsutils apt package.

Let's assume we want to set up DNS hosting for foo.com. To do this, we create a masterdomain object:


Start serving DNS records

To create a master domain and enable the DNS server for a specific domain, the syntax is create masterdomain DOMAIN.TLD. Below is an example of doing so:

 [openpanel]% configure domain foo.com
 [domain foo.com]% create masterdomain foo.com
 % Object created with id: 3f5a1ce2-40ec-468f-0b4f-322501a4e5f5
 [domain foo.com]% show masterdomain
 .---------.------------.------.
 | id      | primaryns  | ttl  |
 |---------+------------+------|
 | foo.com | ns.foo.com | 3600 |
 `---------^------------^------'

We can see that a DNS is set up with the above properties for TTL. Keep in mind that if the TTL is manually set, it currently must be set to 300, 3600, 86400 or 604800 (other values aren't accepted due to a shortcoming in the current implementation).

Configuring DNS

We can set the properties of the DNS object and so we can change for example the 'time to live" parameter:

 [domain foo.com]% show  dnsdomain foo.com
 .-------------.------------------.--------------.
 | Field       | Value            | Description  |
 |-------------+------------------+--------------|
 | owner       |                  | Object owner |
 | id          | foo.com          | Domain name  |
 | type        | masterdomain     | Type         |
 | description | Primary TTL=3600 | Description  |
 `-------------^------------------^--------------'
 [domain foo.com]% update dnsdomain foo.com
  primaryns=*     Primary nameserver
  ttl=300         5 minutes
  ttl=3600        1 hour
  ttl=86400       1 day
  ttl=604800      1 week
 [domain foo.com]% update dnsdomain foo.com  ttl=300
 % Object updated


Next we are going to alter the DNS object:

 [domain foo.com]% configure masterdomain foo.com
 [masterdomain foo.com]% show record
 .----.------.------.---------------.--------.
 | id | name | type | address       | mxpref |
 |----+------+------+---------------+--------|
 | 1  | www  | a    | 61.11.127.131 |        |
 | 2  | ns   | a    | 61.11.127.131 |        |
 | 3  | mail | a    | 61.11.127.131 |        |
 | 4  |      | a    | 61.11.127.131 |        |
 | 5  |      | mx   | mail.foo.com. | 10     |
 | 6  |      | ns   | ns.foo.com.   |        |
 `----^------^------^---------------^--------'

This gives an overview of the DNS records of the master DNS server. As we can see, several subdomains are configured by default (www, ns and mail). This behaviour is controlled by the prototype object.


Adding a DNS record

First we add an a record for the general domain (e.g. foo.com):

 [masterdomain foo.com]% create a name= address=123.123.123.24
 % Object created with id: 4c074ca1-9983-47ed-4cde-80797582cbae
 [masterdomain foo.com]% show record
 .----.------.------.----------------.--------.
 | id | name | type | address        | mxpref |
 |----+------+------+----------------+--------|
 | 1  |      | a    | 61.11.127.131  |        |
 | 2  | www  | a    | 61.11.127.131  |        |

We can check whether our DNS works by typing under *nix:

$ host foo.com 127.0.0.1
foo.com has address 61.11.127.131
foo.com mail is handled by 10 mail.foo.com

We can see the recently added ip address for the domain foo.com and we can see that the mail is handled by mail.foo.com

We can add another subdomain:

[masterdomain foo.com]%  create a name=bar address=110.21.12.201
 % Object created with id: 2df6fb3e-cf63-4839-4c20-c37543060559
 [masterdomain foo.com]% show record
 .----.------.------.----------------.--------.
 | id | name | type | address        | mxpref |
 |----+------+------+----------------+--------|
 | 1  |      | a    | 123.123.123.24 |        |
 | 2  | bar  | a    | 110.21.12.201  |        |
 | 3  | www  | a    | 64.71.167.187  |        |
 | 4  | ns   | a    | 64.71.167.187  |        |
 | 5  | mail | a    | 64.71.167.187  |        |
 | 6  |      | a    | 64.71.167.187  |        |
 | 7  |      | mx   | mail.foo.com.  | 10     |
 | 8  |      | ns   | ns.foo.com.    |        |
 `----^------^------^----------------^--------'

This creates an entry which points bar.foo.com to the server at ip address 110.21.12.201

Adding slave DNS

Most registrars will want a secondary (slave) DNS to be set up for a domain.

on a other machine

The most ideal situation is when the secondary DNS runs on a different machine. In the next example the primary DNS runs on a server with ip number 10.244.1.1 and the secondary DSN runs on a server with ip number 10.244.1.2:

 [openpanel]%  configure domain foo.com                                                                                                  
 [domain foo.com]% configure slavedomain foo.com                                                                  
 [slavedomain foo.com]% show                                    
 .----------.------------------.--------------------------.
 | Field    | Value            | Description              |
 |----------+------------------+--------------------------|
 | owner    | openadmin        | Object owner             |
 | id       | openpanel2.3e.nl | Domain name              |
 | masterip | 10.244.1.1       | Master server IP address |
 `----------^------------------^--------------------------'

The secondary DSN will fetch the information from the primary DNS to keep in sync.

on the same machine

Sometimes it is useful to have the primary and the secondary DNS on the same server. In this case it suffices to have two ip numbers configured and just add a second NS record to the masterdomain object:

Add a second NS record to the masterdomain object:

 [masterdomain foo.com]% create a name=ns2 address=10.244.1.2
 % Object created with id: 6191dfef-1655-4877-a216-60a92dfbad79
 [masterdomain foo.com]% create ns  name= address=ns2.foo.com
 % Object created with id: 46d7cd7c-c819-43d1-9ad1-b26e1028aea5
 [masterdomain foo.com]% show record
 .----.------.------.----------------.--------.
 | id | name | type | address        | mxpref |
 |----+------+------+----------------+--------|
 | 1  |      | a    | 10.244.1.1     |        |
 | 2  | bar  | a    | 110.21.12.201  |        |
 | 3  | ns2  | a    | 10.244.1.2     |        |
 | 4  | www  | a    | 10.244.1.1     |        |
 | 5  | ns   | a    | 10.244.1.1     |        |
 | 6  | mail | a    | 10.244.1.1     |        |
 | 7  |      | a    | 10.244.1.1     |        |
 | 8  |      | mx   | mail.foo.com.  | 10     |
 | 9  |      | ns   | ns2.foo.com    |        |
 | 10 |      | ns   | ns.foo.com.    |        |
 `----^------^------^----------------^--------'


We now advertise to the registrar that our primary DNS is ns.bar.com and our secondary DNS is ns2.bar.com.


Configuring a prototype DNS

A prototype DNS is useful when one is creating a lot of DNS domains in the same way. Here is an example how to configure a prototype for dns creation. New domains will get these record by default. The below example shows the way the current prototype is configured on a vanilla install.

 [openpanel]% configure domain $prototype$
 [domain $prototype$]% configure dnsdomain $prototype$
 [masterdomain $prototype$]% create a name= address=<YOURMAINIPADDRESS>
 [masterdomain $prototype$]% create a name=www address=<YOURMAINIPADDRESS>
 [masterdomain $prototype$]% create a name=ns address=<YOURMAINIPADDRESS>
 [masterdomain $prototype$]% create a name=mail address=<YOURMAINIPADDRESS>
 [masterdomain $prototype$]% create ns address=ns
 [masterdomain $prototype$]% create mx address=mail.$prototype$ mxpref=10
 [masterdomain $prototype$]% end                                       

In the example above the $prototype$ "variable" is substituted by the current domainname, when the prototype is applied.

With the creation of a new domain the following happens:

 [openpanel]% create domain bar.com
 % Object created with id: 6ca2997d-cbe9-441d-bcbb-86727d4a3c03
 [openpanel]% configure domain bar.com
 [domain bar.com]% create masterdomain bar.com
 % Object created with id: 3d4b6c01-15bf-416a-ab9b-02d201a341f6
 [domain bar.com]% configure dnsdomain bar.com
 [masterdomain bar.com]% show record
 .----.------.------.---------------.--------.
 | id | name | type | address       | mxpref |
 |----+------+------+---------------+--------|
 | 1  | www  | a    | 42.42.42.42   |        |
 | 2  | ns   | a    | 42.42.42.42   |        |
 | 3  | mail | a    | 42.42.42.42   |        |
 | 4  |      | a    | 42.42.42.42   |        |
 | 5  |      | mx   | mail.bar.com. | 10     |
 | 6  |      | ns   | ns.bar.com.   |        |
 `----^------^------^---------------^--------'

These records are now created by default.

Aliases

Section last confirmed valid for OpenPanel-Cli release: 1.0.0 by AndrewLuecke.

Creating an alias

To create an alias, use the command "create alias <aliasname>". As an example, to have bar.com direct to the same configuration as foo.com (the authorative domain for bar.com should of course also direct to this server):

 [openpanel]% configure domain foo.com
 [domain foo.com]% create alias bar.com
 % Object created with id: 52e3277a-2cc5-462f-4a54-874e310a1572 

Email

Section last confirmed valid for OpenPanel-Cli release: 1.0.0 by AndrewLuecke.

Setting up E-mail

An email domain can be set up under the domain object, just like you can with a dns domain. Under the domain object you can create address objects that are either aliases or physical mailboxes.

Under aliases you can create multiple destination objects by typing: create email <domainname>

 [openpanel]% configure domain foo.com
 [domain foo.com]% create email  foo.com
 % Object created with id: 66f859ed-9d7f-45fd-4296-fcae5dc95e06
 [domain foo.com]% configure email foo.com
 [email foo.com]% create box marco@foo.com password=test123
 % Object created with id: 2ebcb6f6-e177-4ca6-9f3d-c2c93473d4a5
 [email foo.com]% create box pitr@foo.com password=test123 allowimap=true
 % Object created with id: 6c5e76a4-d264-4b3b-6881-2cc571d54fca
 [email foo.com]% create box john@foo.com password=nHfuIr allowpop3=true
 % Object created with id: 4e1097c7-64b2-43d6-c203-b99f403a2d7c
 [email foo.com]% create alias  all@foo.com pridest=john@foo.com
 % Object created with id: 28eb3f7a-cb42-4476-5bc9-6f7e789aea5e
 [email foo.com]% configure alias all@foo.com
 [alias all@foo.com]% create dest address=marco@foo.com
 % Object created with id: 6ffa0471-8146-4adb-0e61-068560fd9c4d
 [alias all@foo.com]% create dest address=pitr@foo.com
 % Object created with id: 38082203-961e-4aff-6d58-e94e74e968fc
 [alias all@foo.com]% create dest address=pi+spambox@foo.com
 % Object created with id: 2b024a2a-22b9-4f53-83ff-33304ea265be
 [alias all@foo.com]% show dest
 .----.--------------------.
 | id | address            |
 |----+--------------------|
 | 1  | marco@foo.com      |
 | 2  | pitr@foo.com       |
 | 3  | pi+spambox@foo.com |
 `----^--------------------'
 [alias all@foo.com]% exit
 [email foo.com]% show address
 .---------------.-------.-----------------.
 | id            | type  | description     |
 |---------------+-------+-----------------|
 | john@foo.com  | box   | pop3  smtp      |
 | marco@foo.com | box   | pop3  smtp      |
 | pitr@foo.com  | box   | pop3 imap smtp  |
 | all@foo.com   | alias | john@foo.com    |
 `---------------^-------^-----------------'


How to delete an alias?

 [email foo.com]% configure alias all@foo.com
 [alias all@foo.com]% show dest
 .----.--------------------.
 | id | address            |
 |----+--------------------|
 | 1  | marco@foo.com      |
 | 2  | pitr@foo.com       |
 | 3  | pi+spambox@foo.com |
 `----^--------------------'
 [alias all@foo.com]% delete dest 1
 Do you really want to delete this item? [y/N] Yes 

 % Object '1' removed
 [alias all@foo.com]% show dest
 .----.--------------------.
 | id | address            |
 |----+--------------------|
 | 1  | pitr@foo.com       |
 | 2  | pi+spambox@foo.com |
 `----^--------------------'


FTP

Section last confirmed valid for OpenPanel-Cli release: 1.0.0 by AndrewLuecke.

Create a FTP Master Account

The syntax to add a FTP account is create ftp-user USERNAME@DOMAIN password=FTPPASSWORD. An example of the process is below:

 [openpanel]% configure domain foo.org
 [domain flightexam.org]% create ftp-user test@foo.org password=foobar
 % Object created with id: 11dae98e-284f-4f4c-28cf-bc6274bedc54

An example connection to that account is below:

 ftp> open foo.org
 Connected to foo.org.
 220---------- Welcome to Pure-FTPd [privsep] [TLS] ----------
 220-You are user number 1 of 50 allowed.
 220-Local time is now 10:18. Server port: 21.
 220-This is a private system - No anonymous login
 220-IPv6 connections are also welcome on this server.
 220 You will be disconnected after 15 minutes of inactivity.
 User (foo.org:(none)): test@foo.org
 331 User test@foo.org OK. Password required
 Password:
 230-User test@foo.org has group access to:  1000     105
 230 OK. Current directory is /
 ftp>

Setting up FTP for Vhosts

You can create ftp-accounts on two levels: On the domain level, with access to all its vhosts, or on the vhost level, with access only to the specific site's directory:

 [openpanel]% configure domain foo.com
 [domain foo.com]% create ftp-user test@foo.com password=test123
 % Object created with id: 62dafaa2-cd98-48c2-1a9b-91de672549ea
 [domain foo.com]% configure vhost www.foo.com
 [vhost www.foo.com]% create ftp-user webdeveloper@www.foo.com password=test1234
 % Object created with id: 266e65ba-0e45-431f-a74d-bd1e590773b1


Quota

Section last confirmed valid for OpenPanel-Cli release: 1.1.1.1 by AndrewLuecke.

Setting up Quotas

Objects and quota of these objects are associated with users. Every user can "own" certain objects and has a quota for every particular kind of object. One can retrieve a list with the usage and quota set for every type of object:

[openpanel]% configure user dave
[user dave]% show quota
.------------------------------.--------------------.---------.-------.-------.
| id                           | description        | units   | usage | quota |
|------------------------------+--------------------+---------+-------+-------|
| User                         | System/OpenPanel   | Objects | 5     | -1    |
|                              | user               |         |       |       |
| MySQL:Database               | MySQL Database     | Objects | 5     | -1    |
| MySQL:DBUser                 | MySQL database     | Objects | 5     | -1    |
|                              | user               |         |       |       |
| MySQL:DBUserhost             | User host/IP match | Objects | 0     | -1    |
| SSH:Shell                    | SSH Shell          | Objects | 0     | -1    |
| Domain                       | A collection of    | Objects | 4     | -1    |
|                              | domain-related     |         |       |       |
|                              | services           |         |       |       |
| Domain:Alias                 | A secondary        | Objects | 1     | -1    |
|                              | aliased domain     |         |       |       |
| Mail                         | Email domain       | Objects | 2     | -1    |
|                              | configuration      |         |       |       |
| Mail:Box                     | Mail box           | Objects | 1     | -1    |
| Mail:Alias                   | Mail alias         | Objects | 1     | -1    |
| Mail:Destination             | Extra alias        | Objects | 0     | -1    |
|                              | destination        |         |       |       |
|                              | address            |         |       |       |
| Domain:Vhost                 | Virtual host       | Objects | 3     | -1    |
|                              | configuration      |         |       |       |
| Domain:HTTPS                 | HTTPS Virtual host | Objects | 0     | -1    |
|                              | configuration      |         |       |       |
| FTP:Master                   | FTP master account | Objects | 2     | -1    |
| FTP:User                     | FTP site account   | Objects | 1     | -1    |
| Mail:SpamAssassin            | SpamAssassin mail  | Objects | 0     | -1    |
|                              | filter             |         |       |       |
| IPTables:Port                | TCP/UDP port       | Objects | 10    | -1    |
|                              | configuration      |         |       |       |
| IPTables:Port:Rule           | IPv4 Port          | Objects | 0     | -1    |
|                              | exception          |         |       |       |
| IPTables:Port:V6Rule         | IPv6 Port          | Objects | 0     | -1    |
|                              | exception          |         |       |       |
| Domain:HTTPForward           | HTTP Forwarding    | Objects | 0     | -1    |
| DNSDomain:Master             | DNS Master zone    | Objects | 3     | -1    |
| DNSDomain:Slave              | DNS Slave zone     | Objects | 0     | -1    |
| DNSDomain:A                  | DNS A record       | Objects | 20    | -1    |
| DNSDomain:AAAA               | DNS AAAA (IPv6)    | Objects | 0     | -1    |
|                              | record             |         |       |       |
| DNSDomain:CNAME              | DNS CNAME record   | Objects | 0     | -1    |
| DNSDomain:MX                 | DNS MX record      | Objects | 5     | -1    |
| DNSDomain:NS                 | DNS NS record      | Objects | 7     | -1    |
| DNSDomain:TXT                | DNS text record    | Objects | 0     | -1    |
| System:AXFR                  | DNS AXFR Slave     | Objects | 0     | -1    |
|                              | Server             |         |       |       |
| Domain:Vhost/traffic         | Web traffic        | MBytes  | 0     | 0     |
| Domain:Vhost/traffic:warning | Web traffic        | MBytes  | 0     | 0     |
|                              | (warning level)    |         |       |       |
| User/diskspace               | Disk usage         | MBytes  | 0     | 0     |
| User/diskspace:warning       | Disk usage         | MBytes  | 0     | 0     |
|                              | (warning level)    |         |       |       |
`------------------------------^--------------------^---------^-------^-------'

We can see from the example above that the creation of new domains by Dave is currently unrestricted (when value equals -1, there is no quota set in place).

The following is an example of how to use quotas to limit a user to only 2 domains on an open panel server using OpenPanel-CLI. The procedure is easily modified for all kinds of quota updates.

 [user dave]% update quota Domain quota=2
 % Object updated
 [user dave]% show quota
.------------------------------.--------------------.---------.-------.-------.
| id                           | description        | units   | usage | quota |
|------------------------------+--------------------+---------+-------+-------|
| User                         | System/OpenPanel   | Objects | 5     | -1    |
|                              | user               |         |       |       |
| MySQL:Database               | MySQL Database     | Objects | 5     | -1    |
| MySQL:DBUser                 | MySQL database     | Objects | 5     | -1    |
|                              | user               |         |       |       |
| MySQL:DBUserhost             | User host/IP match | Objects | 0     | -1    |
| SSH:Shell                    | SSH Shell          | Objects | 0     | -1    |
| Domain                       | A collection of    | Objects | 4     | 2     |
|                              | domain-related     |         |       |       |
|                              | services           |         |       |       |

| Domain:Alias                 | A secondary        | Objects | 1     | -1    |
|                              | aliased domain     |         |       |       |
| Mail                         | Email domain       | Objects | 2     | -1    |
|                              | configuration      |         |       |       |
| Mail:Box                     | Mail box           | Objects | 1     | -1    |
| Mail:Alias                   | Mail alias         | Objects | 1     | -1    |
| Mail:Destination             | Extra alias        | Objects | 0     | -1    |
|                              | destination        |         |       |       |
|                              | address            |         |       |       |
| Domain:Vhost                 | Virtual host       | Objects | 3     | -1    |
|                              | configuration      |         |       |       |
| Domain:HTTPS                 | HTTPS Virtual host | Objects | 0     | -1    |
|                              | configuration      |         |       |       |
| FTP:Master                   | FTP master account | Objects | 2     | -1    |
| FTP:User                     | FTP site account   | Objects | 1     | -1    |
| Mail:SpamAssassin            | SpamAssassin mail  | Objects | 0     | -1    |
|                              | filter             |         |       |       |
| IPTables:Port                | TCP/UDP port       | Objects | 10    | -1    |
|                              | configuration      |         |       |       |
| IPTables:Port:Rule           | IPv4 Port          | Objects | 0     | -1    |
|                              | exception          |         |       |       |
| IPTables:Port:V6Rule         | IPv6 Port          | Objects | 0     | -1    |
|                              | exception          |         |       |       |
| Domain:HTTPForward           | HTTP Forwarding    | Objects | 0     | -1    |
| DNSDomain:Master             | DNS Master zone    | Objects | 3     | -1    |
| DNSDomain:Slave              | DNS Slave zone     | Objects | 0     | -1    |
| DNSDomain:A                  | DNS A record       | Objects | 20    | -1    |
| DNSDomain:AAAA               | DNS AAAA (IPv6)    | Objects | 0     | -1    |
|                              | record             |         |       |       |
| DNSDomain:CNAME              | DNS CNAME record   | Objects | 0     | -1    |
| DNSDomain:MX                 | DNS MX record      | Objects | 5     | -1    |
| DNSDomain:NS                 | DNS NS record      | Objects | 7     | -1    |
| DNSDomain:TXT                | DNS text record    | Objects | 0     | -1    |
| System:AXFR                  | DNS AXFR Slave     | Objects | 0     | -1    |
|                              | Server             |         |       |       |
| Domain:Vhost/traffic         | Web traffic        | MBytes  | 0     | 0     |
| Domain:Vhost/traffic:warning | Web traffic        | MBytes  | 0     | 0     |
|                              | (warning level)    |         |       |       |
| User/diskspace               | Disk usage         | MBytes  | 0     | 0     |
| User/diskspace:warning       | Disk usage         | MBytes  | 0     | 0     |
|                              | (warning level)    |         |       |       |
`------------------------------^--------------------^---------^-------^-------'

As we can see, the usage is at "4", but the quota is lower, which means the user cannot add any more domains without the assistance of an administrator. If the quota was set to 5, the user could add 1 more domain).. To remove the limit, simply update the quota to -1 (unlimited).


Subdomains are regulated by the "vhost" and "mail" quota. In this example the user can still freely add mailhosts, webhosts and dnshosts within their existing domains. It is therefore strongly recommended on production servers to test quota configurations before deployment to ensure that the quotas have been correctly set.

Firewall

Section last confirmed valid for OpenPanel-Cli release: Unknown by Unknown.

Configuring the Firewall

If the IPTables module is loaded, you should be able to access firewall functionality from the root level. First thing you need to do if you want to use it is to enable it. In its default configuration it allows all relevant ports, if you want to make sure you're not going to lock yourself out, first verify that the default rules are there:

 [openpanel]% configure firewall
 [firewall]% show port
 .------.------------------------.--------.---------.
 | id   | description            | state  | filter  |
 |------+------------------------+--------+---------|
 | 110  | E-mail (POP3)          | permit | tcp     |
 | 111  | Sun RPC service        | deny   | tcp-udp |
 | 143  | E-mail (IMAP)          | permit | tcp     |
 | 21   | FTP                    | permit | tcp     |
 | 22   | Secure Shell (SSH)     | permit | tcp     |
 | 25   | Incoming E-mail (SMTP) | permit | tcp     |
 | 4089 | OpenPanel Interface    | permit | tcp     |
 | 443  | Websites (HTTPS)       | permit | tcp     |
 | 53   | DNS                    | permit | tcp-udp |
 | 80   | Websites (HTTP)        | permit | tcp     |
 `------^------------------------^--------^---------'

If they are, you can go ahead and enable the firewall:

 [firewall]% end
 [openpanel]% update firewall enabled=true
 [43391.317994] ip6_tables: (C) 2000-2006 Netfilter Core Team
 % Object updated

In its default inception the firewall follows this basic set-up:

  1.  : Anything not explicitly permitted is denied
  2.  : Any traffic related to a permitted connection is permitted
  3.  : Any traffic to ports as listed in the port list is permitted,
  4.  : Except for those matching more specific rules under a port.

So, to disable access to smtp (using port 25) for any network except your office lan at 192.168.3.0/24, you can do this:

 [openpanel]% configure firewall
 [firewall]% configure port 25
 [port 25]% create  v4exception ip=192.168.3.0 subnet=255.255.255.0 state=permit
 [port 25]% ..
 [firewall]% update port 25 state=deny
 % Object updated

You can do the same for the ssh port, but of course make sure you don't lock yourself out by first creating the state=permit rule before you update the port object to state=deny.

Working from behind a Gateway

Perhaps the server that is controlled by openpanel is behind a firewall or other sort of gateway. This might mean the ip address is not routable to the internet (reserved are the following three blocks of the IP address space for private networks (local networks): 10.0.0.0 - 10.255.255.255, 172.16.0.0 - 172.31.255.255, 192.168.0.0 - 192.168.255.255. Also, IP addresses in the range of 169.254.0.0 -169.254.255.255 are reserved for Automatic Private IP Addressing.)> First thing to do: the gate should redirect the appropriate ports to the internal server. For example redirect web server requests at port 80 to the internal server 10.20.1.23 on the gateway with ip number 19.170.88.100: /sbin/iptables -A PREROUTING -i 19.170.88.100 -t nat -p TCP --dport 80 -j DNAT --to 10.20.1.23:80;

Then we have to make sure the records of DNS server do direct to the gateway and so they should not direct to the internal server!

 [masterdomain foo.com]%  show record
 .----.------.------.-----------------------.--------.
 | id | name | type | address               | mxpref |
 |----+------+------+-----------------------+--------|
 | 1  | www  | a    | 10.20.1.23            |        |
 | 2  | ns   | a    | 10.20.1.23            |        |
 | 3  | mail | a    | 10.20.1.23            |        |
 | 4  |      | a    | 10.20.1.23            |        |
 | 5  |      | mx   | mail.foo.com          | 10     |
 | 6  |      | ns   | ns.foo.com.           |        |
 `----^------^------^-----------------------^--------'

Here we see that the www record has id 1 so we change that:

 [masterdomain foo.com]% update record 1 address=19.170.88.100
 [masterdomain foo.com]% show record
 .----.------.------.-----------------------.--------.
 | id | name | type | address               | mxpref |
 |----+------+------+-----------------------+--------|
 | 1  | ns   | a    | 10.20.1.23            |        |
 | 2  | mail | a    | 10.20.1.23            |        |
 | 3  |      | a    | 10.20.1.23            |        |
 | 4  | www  | a    | 19.170.88.100         |        |
 | 5  |      | mx   | mail.foo.com          | 10     |
 | 6  |      | ns   | ns.foo.com.           |        |
 `----^------^------^-----------------------^--------'

and repeat these steps for every service that is to be reached through the gateway.

Personal tools
Namespaces
Variants
Actions
Documentation
Tools
Toolbox