Skip to content

docs: Update and modernise the "Installing Asterisk" docs #203

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JMadgwick wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Update and modernise the "Installing Asterisk" docs #203

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 29 additions & 21 deletions ...ng-Asterisk/Installing-Asterisk-From-Source/Building-and-Installing-Asterisk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,18 @@ Build and Install Instructions

Now we can compile and install Asterisk. To compile Asterisk, simply type make at the Linux command line.

/// tip | Multithreaded Compilation
You can add the `-jX` argument to `make` to use compile using multiple CPU threads,
e.g. `make -j8` would use 8 threads instead of the single thread default.
This can significantly reduce compile time on machines with multiple threads available.
However, supplying a greater number of threads than available will instead reduce performance.
///

```
[root@server asterisk-14.X.Y]# make
[root@server asterisk-22.X.Y]# make
```

The compiling step will take several minutes, and you'll see the various file names scroll by as they are being compiled. Once Asterisk has finished compiling, you'll see a message that looks like:
The compiling step can take several minutes, and you'll see the various file names scroll by as they are being compiled. Once Asterisk has finished compiling, you'll see a message that looks like:

```
+--------- Asterisk Build Complete ---------+
Expand All @@ -24,10 +31,10 @@ The compiling step will take several minutes, and you'll see the various file na
+--------- Asterisk Build Complete ---------+
```

On this PageAs the message above suggests, our next step is to install the compiled Asterisk program and modules. To do this, use the **make** **install** command.
As the message above suggests, our next step is to install the compiled Asterisk program and modules. To do this, use the **make install** command.

```
[root@server asterisk-14.X.Y]# make install
[root@server asterisk-22.X.Y]# make install
```

When finished, Asterisk will display the following warning:
Expand Down Expand Up @@ -69,53 +76,54 @@ In some environments, it may be necessary or useful to modify parts of the build
Specific flags can be passed to `gcc` when Asterisk is configured, using the `CFLAGS` and `LDFLAGS` environment variables:

```
[root@server asterisk-14.X.Y]# ./configure CFLAGS=-pg LDFLAGS=-pg
[root@server asterisk-22.X.Y]# ./configure CFLAGS=-pg LDFLAGS=-pg
```

### Debugging compilation

To see all of the flags passed to gcc, build using the `NOISY_BUILD` setting set to `YES`:

```
[root@server asterisk-14.X.Y]# make NOISY_BUILD=yes
[root@server asterisk-22.X.Y]# make NOISY_BUILD=yes
```

### Building for non-native architectures

Generally, Asterisk attempts to optimize itself for the machine on which it is built on. On some virtual machines with virtual CPU architectures, the defaults chosen by Asterisk's compilation options will cause Asterisk to build but fail to run. To disable native architecture support, disable the `BUILD_NATIVE` option in menuselect:

```
[root@server asterisk-14.X.Y]# menuselect/menuselect --disable BUILD_NATIVE menuselect.makeopts
[root@server asterisk-22.X.Y]# menuselect/menuselect --disable BUILD_NATIVE menuselect.makeopts

[root@server asterisk-14.X.Y]# make
[root@server asterisk-22.X.Y]# make
```

### Installing to a custom directory

While there are multiple ways to sandbox an instance of Asterisk, the preferred mechanism is to use the `--prefix` option with the `configure` script:

```
[root@server asterisk-14.X.Y]# ./configure --prefix=/usr/local/my_special_folder
[root@server asterisk-22.X.Y]# ./configure --prefix=/usr/local/my_special_folder
```

Note that the default value for `prefix` is `/usr/local`.

Other Make Targets
------------------

| Target | Description |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| | Executing `make` with no target is equivalent to the `all` target. |
| **all** | Compiles everything everything selected through the `configure` and `menuselect` scripts. |
| Target | Description |
|-------------------|-------------|
| | Executing `make` with no target is equivalent to the `all` target. |
| **menuselect** | Access the Menuselect system. |
| **all** | Compiles everything everything selected through the `configure` and `menuselect` scripts. |
| **full** | This is equivalent to `make` or `make all`, save that it will perform a more thorough investigation of the source code for documentation. This is needed to generate [AMI event documentation](/Development/Roadmap/Asterisk-11-Projects/AMI-Event-Documentation). Note that your system must have Python in order for this make target to succeed. |
| **install** | Installs Asterisk, building Asterisk if it has not already been built. In general, this should be executed after Asterisk has successfully compiled. |
| **uninstall** | Removes Asterisk binaries, sounds, man pages, headers, modules and firmware builds from the system. |
| **uninstall-all** | Same as the `uninstall` target, but additionally removes configuration, spool directories and logs. All traces of Asterisk. |
| **clean** | Remove all files generated by make. |
| **dist-clean** | Remove pretty much all files generated by make and configure. |
| **samples** | Install all sample configuration files (.conf files) to `/etc/asterisk/`. Overwrites existing config files. |
| **config** | Install init scripts (startup scripts) on your system. |
| **progdocs** | Uses doxygen to locally generate HTML development documentation from the source code. Generated in the `doc/` subdirectory of the source; see `doc/index.html`. |
| **install** | Installs Asterisk, building Asterisk if it has not already been built. In general, this should be executed after Asterisk has successfully compiled. |
| **uninstall** | Removes Asterisk binaries, sounds, man pages, headers, modules and firmware builds from the system. |
| **uninstall-all** | Same as the `uninstall` target, but additionally removes configuration, spool directories and logs. All traces of Asterisk. |
| **clean** | Remove all files generated by make. |
| **dist-clean** | Remove pretty much all files generated by make and configure. |
| **samples** | Install all sample configuration files (.conf files) to `/etc/asterisk/`. Overwrites existing config files. |
| **config** | Install init scripts (startup scripts) on your system. |
| **progdocs** | Uses doxygen to locally generate HTML development documentation from the source code. Generated in the `doc/` subdirectory of the source; see `doc/index.html`. |

/// note | Version Notice
The `full` build target is only available in Asterisk 11 and later
Expand Down
4 changes: 2 additions & 2 deletions ...g-Asterisk/Installing-Asterisk-From-Source/Installing-Initialization-Scripts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ pageid: 4817521
Now that you have Asterisk compiled and installed, the last step is to install the initialization script, or `initscript`. This script starts Asterisk when your server starts, will monitor the Asterisk process in case anything *bad* happens to it, and can be used to stop or restart Asterisk as well. To install the `initscript`, use the **make** **config** command.

```
[root@server asterisk-14.X.Y]# make config
[root@server asterisk-22.X.Y]# make config
```

As your Asterisk system runs, it will generate logfiles. It is recommended to install the `logrotation` script in order to compress and rotate those files, to save disk space and to make searching them or cataloguing them easier. To do this, use the **make install-logrotate** command.

```
[root@server asterisk-14.X.Y]# make install-logrotate
[root@server asterisk-22.X.Y]# make install-logrotate
```
4 changes: 3 additions & 1 deletion .../Installing-Asterisk/Installing-Asterisk-From-Source/Installing-Sample-Files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,14 @@ for standard deployments.
While installing the sample configuration files may be a good starting
point for some people, they should not be viewed as recommended
configuration for an Asterisk system.
See [Hello World](../../Hello-World.md) for further information on
the minimum set of required Asterisk Configs.
///

To install a set of sample configuration files for Asterisk, type:

```
[root@server asterisk-14.X.Y]# make samples
[root@server asterisk-22.X.Y]# make samples
```

Any existing sample files which have been modified will be given a **.old** file extension. For example, if you had an existing file named **extensions.conf**, it would be renamed to **extensions.conf.old** and the sample dialplan would be installed as **extensions.conf**.
16 changes: 8 additions & 8 deletions .../Installing-Asterisk-From-Source/Prerequisites/Building-and-Installing-DAHDI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,14 @@ pageid: 4817510
Overview
========

/// note | Don't need DAHDI?
If you are not integrating with any traditional telephony equipment
and you are not planning on using the
[MeetMe](/Latest_API/API_Documentation/Dialplan_Applications/MeetMe)
dialplan application, then you do not have to install DAHDI or libpri
in order to use Asterisk.
///

Let's install DAHDI!

On Linux, we will use the **DAHDI-linux-complete** tarball, which contains the DAHDI Linux drivers, DAHDI tools, and board firmware files. Again, we're assuming that you've untarred the tarball in the `/usr/local/src` directory, and that you'll replace X and Y with the appropriate version numbers.
Expand All @@ -17,14 +25,6 @@ libpri 1.4.13 and later source code depends on DAHDI include
files. So, one must install DAHDI before installing libpri.
///

// note | Don't need DAHDI?
If you are not integrating with any traditional telephony equipment
and you are not planning on using the
[MeetMe](/Latest_API/API_Documentation/Dialplan_Applications/MeetMe)
dialplan application, then you do not have to install DAHDI or libpri
in order to use Asterisk.
///

Starting with DAHDI-Linux-complete version 2.8.0+2.8.0, all files necessary to install DAHDI are available in the complete tarball. Therefore, all you need to do to install DAHDI is:

```
Expand Down
29 changes: 11 additions & 18 deletions ...Installing-Asterisk-From-Source/Prerequisites/Checking-Asterisk-Requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,27 +5,23 @@ pageid: 4817512

## Configuring Asterisk

Now it's time to compile and install Asterisk. Let's change to the directory which contains the Asterisk source code.
Now it's time to compile and install Asterisk.

```
[root@server]# cd /usr/local/src/asterisk-14.X.Y
```

Next, we'll run a command called **./configure**, which will perform a number of checks on the operating system, and get the Asterisk code ready to compile on this particular server.
In the directory containing the extracted Asterisk source code, run the **./configure** script, which will perform a number of checks on the operating system, and get the Asterisk code ready to compile on this particular server.

```
[root@server asterisk-14.X.Y]# ./configure
[root@server asterisk-22.X.Y]# ./configure
```

This will run for a couple of minutes, and warn you of any missing system libraries or other dependencies. Unless you've installed all of the [System Requirements](/Operation/System-Requirements) for your version of Asterisk, the **configure** script is likely to fail. If that happens, resolve the missing dependency manually, or use the [install_prereq](#using-install_prereq) script to resolve all of the dependencies on your system.
This will run for a couple of minutes, and warn you of any missing system libraries or other dependencies. Unless you've already installed all [System Requirements](/Operation/System-Requirements) for your version of Asterisk, the **configure** script is likely to fail. If that happens, resolve the missing dependency manually, or use the [install_prereq](#using-install_prereq) script to resolve all dependencies on your system.

Once a dependency is resolved, run **configure** again to make sure the missing dependency is fixed.

/// tip
If you have many missing dependencies, you may find yourself running
If you have many missing dependencies, you may find yourself re-running
`configure` a lot. If that is the case, you'll do yourself a favor by
checking the [System Requirements](/Operation/System-Requirements) or
installing all dependencies via the `install_prereq` script.
installing all dependencies via the [`install_prereq`](#using-install_prereq) script, or checking
the [System Requirements](/Operation/System-Requirements) and installing manually.
///

Upon successful completion of **./configure**, you should see a message that looks similar to the one shown below. (Obviously, your host CPU type may be different than the below.)
Expand Down Expand Up @@ -67,7 +63,7 @@ the following command to completely clear out any cached data from the
Asterisk build system.

```
[root@server asterisk-14.X.Y]# make distclean
[root@server asterisk-22.X.Y]# make distclean
```

You can then re-run `./configure`.
Expand All @@ -85,13 +81,10 @@ The **install_prereq** script is included with every release of Asterisk in the
/// warning
You should always use your operating system's package management tools
to ensure that your system is running the latest software *before*
running `install_prereq`. Ubuntu 14's libsnmp-dev package, for
instance, has an issue where it will attempt to remove critical system
packages if the system isn't updated before an attempt is made to
install that package.
running `install_prereq`.
///

```
[root@server asterisk-14.X.Y]# ./contrib/scripts/install_prereq install
[root@server asterisk-14.X.Y]# ./contrib/scripts/install_prereq install-unpackaged
[root@server asterisk-22.X.Y]# ./contrib/scripts/install_prereq install
[root@server asterisk-22.X.Y]# ./contrib/scripts/install_prereq install-unpackaged
```
Loading