/
FreePBX Open Source - Install v17 with ISO Distro

FreePBX Open Source - Install v17 with ISO Distro

Table of Contents

Released in February 2025 and currently in BETA, the v17 ISO is based on Debian 12 ISO and should help automate the process for installing a complete FreePBX or PBXact 17 system with the underlying OS configured appropriately as outlined in this freepbx.org blog post.

Also released as open source is the Ansible role to generate your own FreePBX installation ISOs - see the sngfd12 repo in the FreePBX GitHub!

Video of the big reveal of the 17 ISO

AstriCon 2025 featured a session that covered the new FreePBX v17 ISO and discussed some of the options you will encounter during installation (starting at 19m28s below):

https://www.youtube.com/watch?v=SwlY2Un7V3Q&list=PLighc-2vlRgSpA7t5uGeSZPDsnWcOhRqz&index=17&t=19m28s

 

Step by Step instructions

On-Prem

  1. Download the ISO.

  2. Write the ISO to a USB stick.

    1. Use a USB smaller than 100G. LARGER STICKS WILL BE TREATED AS RAID MEMBERS AND GET WIPED.

    2. Careful with the ddtool on GNU/Linux and BSDs so that you don’t write to the wrong disk!

  3. Confirm DHCP is working on your network.

    1. (Ideally) Assign an IPv4 reservation for the MAC address of your PBX’s connected Ethernet interface. If using multiple interfaces, use the interface with the lowest number / earliest alphabetical MAC.

    2. Try to get local DNS working on your network so your target machine will get a friendly host name.

  4. Prepare your target machine.

    1. Only connect the primary Ethernet interface.

    2. Multiple hard disks will turn into a RAID. NVMe DISKS MAY HAVE ISSUES (Update March 2026 - single NVMe should be fine, issue is now only with multiple NVMe disk and mixed NVMe/SATA disk environments.)

    3. Make sure there’s nothing on the disks that you care about saving.

    4. Insert the USB stick into the target.

  5. Boot your target and immediately enter the BIOS. Usually this is by pressing a key eg. Delete, F1, F9, Escape, etc.

    1. Switch your system to UEFI boot from the USB. This will vary by motherboard.

    2. Save and exit the BIOS.

    3. THE MOST PROPER RAID SETUPS WITH SYNCHRONIZED BOOT LOADERS REQUIRE UEFI not legacy GRUB/ISOLINUX.

  6. The GRUB/ISOLINUX installation screens should look something like Figure I below.

    1. Say “Howdy!” to Tango the FreePBX frog mascot and Kit the Asterisk robot mascot.

    2. Use the arrow keys on your keyboard to navigate the menu. Or, use the single-key shortcuts in bold e.g. press h for Help tips, or b to Begin installation.

      White menu text and yellow help text below that, along with Sangoma, FreePBX and Asterisk mascots and logos, on a mostly black background with a little purple in the corner. Title is Sangoma FreePBX Distro BIOS Installer menu.
      Figure I: Initial GRUB Legacy BIOS/ISOLINUX bootloader installation screen.

       

  7. As you begin installation, refer to the FreePBX.org blog post for details about what “spice level” options to choose, or if you are in a hurry, consider these suggestions:

    1. If you have custom hardware with physical DAHDI interfaces such as Sangoma T1/E1/FXO/FXS cards, choose PUB.

    2. If you do not have any physical telephony hardware and never plan to, you might try FOG instead.

    3. If you want only open source software installed on your final product, check out OSO but heads up it can be a bear on cutting edge hardware without non-free firmware.

    4. If you have Sangoma appliances larger than the UC40, consider UPG.

    5. If you are mimicking a warehouse factory Sangoma install or working with Sangoma support, probably you should select INT.

      Very similar colors and layout as Figure I. But this next menu shows each spice level - PUB, FOG, OSO, UPG, and INT - with description of them at the bottom.
      Figure II: Some of the various spice levels of the bootloader installation (older ISOLINUX version).

       

  8. Next pick your Asterisk version to start with (you can change it later post-install). Asterisk 22 is the best choice for long-running modern installs at this time (March 2026).

    Again same color scheme as Figures I and II. This menu shows Asterisk versions 18, 20, 21, 22, and 23, along with their respective release types (Standard or LTS) plus EOL dates at the bottom.
    Figure III: Choose initial Asterisk version. Note the EOL dates at the bottom might not be in sync with upstream Asterisk by the time you read this.

 

  1. Then pick your final options, such as SERIAL port based installation, disk partition guidance like SLAB, etc. The default partitioning scheme (option 1) is to automatically separate things out a bit into multiple different disk partitions, so that you don’t fill up your hard drive accidentally with a bunch of chatty logs or call recordings. But the SLAB option (new in March 2026) lets you keep things the more traditional FreePBX way in one large root partition and smaller boot and swap partitions.

    Same colors as Figures I, II and III. This menu shows options for a default, serial, slab, serial slab and testing.
    Figure IV: The new SLAB option for crude disk partitioning is highlighted.

 

  1. That concludes the GRUB steps. Next, moving on to the DEBIAN steps, depending on your spice level, you may need to choose your language, locale and keymap.

    Standard Debian text install screen for choosing Language from a list, with English as the red highlighted default on a light gray background.
    Figure V: Language selection. Locale and keymap selections will look similar.

 

  1. Installation of Debian packages will continue. Lots of things will flash on your screen.

  2. After about 5-10 minutes, a prompt may appear (depending on your “spice level” selection in Step #7) showing the automatically generated password for the sangoma user (as shown in Figure VI.)

    1. Copy your generated password to a safe location.

    2. You can change the password if you like - follow the instructions shown on screen.

      1. Press CTRL+ALT+F2 to enter a terminal window.

      2. Type: chroot /target

      3. passwd sangoma

      4. Enter a new password.

      5. Press CTRL+ALT+F1 to return to this dialog.

    3. Press Enter to continue and the system should reboot in a minute or two.

      Screenshot_2025-02-06_13-48-45.png
      Figure VI: Generated password for the sangoma user as shown for some of the installation spice levels.

 

  1. Installation should automatically reboot a couple of times and continue downloading and installing packages over the next appx. 10-30 minutes.

  2. When complete, access the FreePBX web GUI in your browser at the IP address you reserved previously in Step #3.

  3. Setup secure usernames and passwords for web access (similar to FreePBX versions before 17.)

  4. Please note that for security purposes, the root user login via local/remote command line terminal is disabled by default on the v17 ISO. This means that when you login as the sangoma user, at the keyboard or via SSH, then in order to run commands that require elevated privileges, such as fwconsole, you will need to use the sudo command. For example:

    $ sudo fwconsole ma upgradeall ; # elevated to the root user $ sudo -u asterisk fwconsole firewall restart ; # elevated to the asterisk user (sufficient for some fwconsole usage)

 

Cloud

Generally, the same as above for On-Prem, except the method to get the ISO attached to your cloud will differ e.g. probably not USB in the cloud.

Also, choose the FOG spice level at the GRUB/ISOLINUX installation prompt in Step #7.

 

Hybrid

Follow both the On-Prem and Cloud instructions, on two separate systems, one local and one remote. Then, use the FreePBX Advanced Recovery module to link the systems together.