> For the complete documentation index, see [llms.txt](https://mariadb.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mariadb.com/docs/maxscale/maxscale-management/deployment/installation-and-configuration/maxscale-installation-guide.md).

# MaxScale Installation Guide

Install MariaDB MaxScale on Linux using official package repositories, RPM/DEB files, or a tarball. This guide details setup for RHEL, Debian, and SLES, plus the kernel memory-overcommit setting MaxSc

## MariaDB MaxScale Installation Guide

We recommend to install MaxScale on a separate server, to ensure that there can be no competition of resources between MaxScale and a MariaDB Server that it manages.

### Install MariaDB MaxScale From MariaDB Repositories

The recommended approach is to use [the MariaDB package repository](https://github.com/mariadb-corporation/mariadb-docs/tree/main/server/server-management/install-and-upgrade-mariadb/mariadb-package-repository-setup-and-usage.md) to install MaxScale. After enabling the repository by following the instructions, MaxScale can be installed with the following commands.

* For RHEL/Rocky Linux/Alma Linux, use `dnf install maxscale`.
* For Debian and Ubuntu, run `apt update` followed by `apt install maxscale`.
* For SLES, use `zypper install maxscale`.

By default this also installs the `maxscale-maxctrl` package, if available, which is the command line client for administering MaxScale. If you do not want it to be installed, use the following:

* For RHEL/Rocky Linux/Alma Linux, use `dnf install --setopt install_weak_deps=False maxscale`.
* For Debian and Ubuntu, run `apt update` followed by `apt install --no-install-recommends maxscale`.
* For SLES, use `zypper install --no-recommends maxscale`.

In order to use the `maxctrl` command line client, you'll need to install Node.js. The minimum required version is Node.js 10 but we recommend using the latest LTS release of Node.js.

### Install MariaDB MaxScale From a RPM/DEB Package

Download the correct MaxScale package for your CPU architecture and operating system from the [MariaDB Downloads page](https://mariadb.com/downloads/enterprise/enterprise-maxscale/). MaxScale can be installed with the following commands.

* For RHEL/Rocky Linux/Alma Linux, use `dnf install /path/to/maxscale-*.rpm`
* For Debian and Ubuntu, use `apt install /path/to/maxscale-*.deb`.
* For SLES, use `zypper install /path/to/maxscale-*.rpm`.

### Install MariaDB MaxScale Using a Tarball

MaxScale can also be installed using a tarball. This may be required if you are using a Linux distribution for which there exist no installation package or if you want to install many different MaxScale versions side by side. For instructions on how to do that, please refer to [Install MariaDB MaxScale using a Tarball](/docs/maxscale/maxscale-management/deployment/installation-and-configuration/installing-maxscale-using-a-tarball.md).

### Assumptions

#### Memory allocation behavior

MaxScale assumes that memory allocations always succeed and in general does not check for memory allocation failures. This assumption is compatible with the Linux kernel parameter [vm.overcommit\_memory](https://www.kernel.org/doc/Documentation/vm/overcommit-accounting) having the value `0`, which is also the default on most systems.

With `vm.overcommit_memory` being `0`, memory *allocations* made by an application never fail, but instead the application may be killed by the so-called OOM (out-of-memory) killer if, by the time the application actually attempts to *use* the allocated memory, there is not available free memory on the system.

If the value is `2`, then a memory allocation made by an application may fail and unless the application is prepared for that possibility, it will likely crash with a SIGSEGV. As MaxScale is not prepared to handle memory allocation failures, it will crash in this situation.

The current value of `vm.overcommit_memory` can be checked with this command:

```bash
sysctl vm.overcommit_memory
```

Alternatively, use this command:

```bash
cat /proc/sys/vm/overcommit_memory
```

### Next Steps

MaxScale is installed. Configuring, administering and backing it up are covered in full elsewhere, so this guide only points at them:

* [The MaxScale Tutorial](/docs/maxscale/mariadb-maxscale-tutorials/setting-up-mariadb-maxscale.md) covers the first steps in configuring your installation — follow it to configure and start using MaxScale.
* The [Configuration Guide](/docs/maxscale/maxscale-management/deployment/installation-and-configuration/maxscale-configuration-guide.md) is the complete parameter reference, including [Encrypting Passwords](/docs/maxscale/maxscale-management/deployment/installation-and-configuration/maxscale-configuration-guide.md#encrypting-passwords) for the configuration file, [Administration](/docs/maxscale/maxscale-management/deployment/installation-and-configuration/maxscale-configuration-guide.md#administration), and [Backing Up a MaxScale Installation](/docs/maxscale/maxscale-management/deployment/installation-and-configuration/maxscale-configuration-guide.md#backing-up-a-maxscale-installation). Module-specific parameters are in the [reference](/docs/maxscale/reference.md).
* [maxctrl](/docs/maxscale/reference/maxscale-maxctrl.md) is the command line client for a running MaxScale, and the [administration tutorial](/docs/maxscale/mariadb-maxscale-tutorials/maxscale-administration-tutorial.md) covers the common administration tasks.

<sub>*This page is licensed: CC BY-SA / Gnu FDL*</sub>

{% @marketo/form formId="4316" %}