Getting started

This chapter takes you from a freshly installed PhonixPBX to the first working call. How to write the disk image or create the container is described in the installation guide (docs/INSTALL.md in the source repository); here we start with the first boot.

First boot and the address of the PBX

Connect the network cable and power on. The first network card gets its address via DHCP. The first boot takes one to two minutes. During it, the PBX:

• enlarges the data partition to fill the disk,
• creates the database, a self-signed HTTPS certificate and the SSH host keys,
• generates a random password for the administrator admin.

When it is ready, the screen (and the serial console, 115200 baud) shows a banner like this:

  PhonixPBX 1.3.0

  LAN (eth0, DHCP): 192.168.1.23
  Web interface: https://192.168.1.23/
                 https://phonix.local/

  Initial login: admin / 3W7YaMJMUei5
  (you must change the password at the first login)

If the box has no screen, you have two other ways to find it:

• Open https://phonix.local/ (or https://<hostname>.local/ once you have changed the host name). The PBX announces itself on the LAN with mDNS; this works on macOS, iOS, Windows 10 and newer, Android 12 and newer, and Linux with nss-mdns. The announcement can be switched off under System → General Setup.
• Look up the address in the DHCP lease list of your router.

In a container, the initial password is printed in the container log (docker logs phonix) or on the container console instead; mDNS is not available in the OCI image.

Logging in

1. Open https://<address>/ in a browser. Plain http:// is redirected to HTTPS.
2. The PBX uses a self-signed certificate until you install a proper one, so the browser warns you the first time. Check that the address is right and accept the warning. To get rid of the warning, obtain a free certificate from Let’s Encrypt or upload your own under Advanced → Certificate.
3. On the page Login to your PBX, enter the username admin and the initial password from the console, then click Sign in.

After five failed attempts within five minutes, the login is blocked for a few minutes (Too many failed attempts. Please wait a few minutes.).

If the initial password is lost, reset it with the console menu: Reset administrator password.

Changing your password

At the first login you are taken straight to the page Change password with the note Please choose your own password before continuing. Other pages are not available until you have set your own password.

You can change your password at any time: open the user menu (your initials at the top right) and choose Change password.

Further administrators, and new passwords for them, are managed under Advanced → Administrators.

Preferences: the interface language

Open the user menu and choose Preferences. Under Language you pick the language of the web interface for your own account; English (default) is used when nothing is selected. The setting is stored per administrator and takes effect immediately after Save.

The language of the voice prompts that callers hear is a different setting, see System → General Setup.

Finding your way around

• The menu on the left has the same sections as AskoziaPBX: System, Accounts, Dialplan, Services, Status and Advanced. Click a section to open its pages. On small screens the menu is folded behind the button at the top.
• The PhonixPBX logo leads to Status → Summary, the start page.
• The top bar shows the host name of the PBX, the moon or sun icon to switch between dark mode and light mode (your browser remembers the choice), and the user menu with Preferences, Change password and Logout.
• Every page has a Help button (question mark) at the right of the page title. It opens the matching chapter of this manual.
• The footer shows the installed version, a link to this Manual and to the interactive API documentation. PhonixPBX in the footer links to the project website phonixpbx.org.

After a period of inactivity you are logged out automatically; the time is set under Advanced → GUI Options.

Lists

Lists such as Accounts → Phones can be searched and are shown in pages. The search field and the page size sit above the table, the page links below it.

• Search: type into the search field above the list (its placeholder names the columns that are searched, for phones Extension, name or description). The list follows as you type, shortly after you stop; Enter searches at once and the × in the field clears it. The search finds the text anywhere in those columns, and upper and lower case do not matter, also for umlauts and other accents: “mei” finds “Meier”, “müller” finds “Müller”. The matches are highlighted in the rows. Next to the field the number of phones is shown, with a search the matches out of all, for example 11 of 64. When nothing matches, the list says so, for example No phones found, with a button Clear search.
• Per page: choose how many rows a page shows: 25, 50 (the default), 100 or All.
• Page links: when the list does not fit on one page, the bottom line shows which rows you see (for example 51–100 of 500) and links to the first and last page, the pages around the current one, and ‹ and › for the previous and next page.

The search, the page and the page size are part of the address in the browser (for example /accounts/phones?q=meier&page=2). Reloading the page, the back button, a bookmark or a link you send to a colleague show the same view. A new visit from the menu starts without a search, on the first page with 50 rows.

After you delete a row, the counts and page links are updated with the next search or page change.

Saving and applying changes

PhonixPBX separates saving from activating. When you save a form, the change is stored in the database right away, but the telephone system still runs with the old configuration. A yellow banner appears at the top of every page:

Pending changes — the configuration has been changed (Phones and providers, Dialplan). Apply to activate.

The list in brackets names the areas that have changed. Click Apply changes to activate them. The PBX then generates the configuration files, writes only the files that actually changed and reloads only the affected parts (for example the SIP stack or the dialplan). Running calls are normally not interrupted.

• On success the banner turns green: Configuration applied., with the number of reload actions.
• If something fails, the banner shows Applying the configuration failed. with the error messages and stays, so you can correct the input and apply again.

You can make several changes and apply them together. The banner names these areas:

Some actions take effect immediately, without Apply changes:

• switching the mode of business hours (Automatic, Open, Closed) on the Business Hours page, through the API or with the feature code on a phone,
• your password and language, administrators and API tokens,
• the options under Advanced → GUI Options,
• installing, regenerating or requesting a certificate under Advanced → Certificate,
• restoring a backup (it is applied as part of the restore), firmware updates, reboot and factory reset.

Changing the IP address under System → Network interrupts your connection when you apply it. Open the new address afterwards.

The console menu

On the local screen (tty1) and on the serial console, PhonixPBX shows the banner with its address followed by a menu. In an LXC/Incus container it runs on the container console; in the OCI container start it with docker exec -it phonix phonix tui. Physical access to the console counts as authorisation, so the menu has no login. Type the number of an entry and press Enter:

The console menu is always in English.

Next steps

A typical setup goes in this order:

1. System → General Setup: host name and domain, time zone, tones and the language of the voice prompts. Check System → Network if the PBX needs a static address or sits behind a NAT router.
2. Accounts → Providers: add your SIP provider account, with dial patterns for outgoing calls.
3. Accounts → Phones: create a phone for every desk phone or softphone and enter the credentials in the device.
4. Incoming routes: on the provider, choose which phone, call group or IVR menu receives incoming calls, see Incoming routes.
5. Apply changes in the yellow banner.
6. Test: check under Status → Calls & Registrations that the phones and the provider are registered, call between two phones, dial out, call in from a mobile phone. The test numbers help, for example 00003246 for an echo test.

After that, set up what you need: e-mail notifications for voicemail, call groups, business hours, IVR menus, and a first backup.