Allow Leilani To Manage Voicemail on an Asterisk Server
Leilani Voicemail Integration Guide (Asterisk / Debian)
This guide explains how to configure a Debian or Ubuntu server running Asterisk so that Leilani can remotely manage
voicemail on behalf of users.
Leilani connects using a restricted SFTP account. The account is jailed to a limited portion of the filesystem and only
has read-only access to the Asterisk voicemail directories.
Requirements
Before beginning, ensure you have:
- Root or sudo access to a Debian/Ubuntu server running Asterisk
- OpenSSH (sshd) installed and running
- A Leilani agent registered to an extension on the same Asterisk server
- Network access allowing TCP port 22 (or your configured SSH port) from Leilani to your server
1. Create the SFTP User
Create a dedicated user that will only be used by Leilani.
sudo useradd -s /usr/sbin/nologin -M leilani
Explanation of the options:
- -s /usr/sbin/nologin
Prevents the user from logging in with a shell.
- -M
Prevents creation of a home directory.
- leilani
The username that will be used by Leilani when connecting over SFTP.
Set a password for the user:
sudo passwd leilani
Because this account is used programmatically by Leilani, it is recommended to use a random password of at least 32
characters.
2. Create the Chroot Jail
The SFTP user must be restricted to a controlled directory on the filesystem.
Create the directory:
sudo mkdir -p /sftp/leilani
Set the required permissions:
sudo chown root:root /sftp /sftp/leilani
sudo chmod 755 /sftp /sftp/leilani
Important:
- The directory used for an SSH chroot must be owned by root
- It must not be writable by other users
If these permissions are incorrect, SSH will refuse the connection.
3. Create Mount Points Inside the Jail
The jail needs directories that mirror where Asterisk stores voicemail data.
Create the required directories:
sudo mkdir -p /sftp/leilani/var/spool/asterisk/voicemail/default
sudo mkdir -p /sftp/leilani/etc/asterisk
Create a placeholder for the voicemail configuration file:
sudo touch /sftp/leilani/etc/asterisk/voicemail.conf
These directories will later be connected to the real system paths using bind mounts.
4. Configure Persistent Bind Mounts
Bind mounts expose specific system directories inside the SFTP jail.
This allows Leilani to read voicemail files while preventing access to the rest of the server.
Edit /etc/fstab:
sudo nano /etc/fstab
Add the following lines:
/var/spool/asterisk/voicemail/default /sftp/leilani/var/spool/asterisk/voicemail/default none bind 0 0
/etc/asterisk/voicemail.conf /sftp/leilani/etc/asterisk/voicemail.conf none bind 0 0
/sftp/leilani/var/spool/asterisk/voicemail/default /sftp/leilani/var/spool/asterisk/voicemail/default none remount,bind,ro 0 0
/sftp/leilani/etc/asterisk/voicemail.conf /sftp/leilani/etc/asterisk/voicemail.conf none remount,bind,ro 0 0
What these mounts do:
- The first two lines expose the real Asterisk directories inside the SFTP jail.
- The second two lines remount those directories as read-only.
- This allows Leilani to read voicemail files but prevents modification or deletion.
Apply the mounts immediately:
sudo mount -a
Verify they were applied:
mount | grep /sftp/leilani
Because these entries are in /etc/fstab, the mounts will automatically be restored after every reboot.
5. Configure SSH to Restrict the User to SFTP
Edit the SSH daemon configuration:
sudo nano /etc/ssh/sshd_config
Ensure the SFTP subsystem is configured:
Subsystem sftp internal-sftp
Add the following block to the end of the file:
Match User leilani
ChrootDirectory /sftp/leilani
ForceCommand internal-sftp -R -d /
PermitTTY no
Explanation of these settings:
- Match User leilani
Applies these restrictions only to the Leilani user.
- ChrootDirectory /sftp/leilani
Restricts filesystem access to the SFTP jail.
- ForceCommand internal-sftp
Prevents shell access and forces the SFTP subsystem.
- -R
Enables read-only mode.
- -d /
Sets the jail root as the starting directory.
- PermitTTY no
Disables terminal access.
Reload the SSH service:
sudo systemctl reload sshd || sudo systemctl reload ssh
6. Configure the Mailbox URL in Leilani
Within the Leilani Console:
1. Navigate to Configuration
2. Locate the Mailbox setting
3. Enter the SFTP connection URL
Example:
sftp://leilani:[password]@[host:port]
Replace the following values:
- leilani — the SFTP username
- [password] — the password created earlier
- [host] — your server hostname or IP address
- [port] — optional if using the default SSH port (22)
Save the configuration.
Result
Leilani will now automatically discover voicemail mailboxes and allow users to retrieve messages through the voice
interface.
Users can:
- Say "voicemail"
- Dial *86
They will be prompted for their mailbox PIN, after which Leilani will retrieve and play their voicemail messages.