A Python API wrapper and toolset for interacting with Synology NAS devices using DiskStation Manager (DSM). The repository provides two different toolsets to communicate with your NAS:
- API: Through a Python wrapper simplifying DSM queries.
- Command system: Through sh scripts hosted in the device, but called from any unix system capable of running
fabricand python.
API requires valid credentials as described in the section below.
Install the package with pip:
python -m pip install synotoolsUnix users (Linux, Mac)
Create your credentials file in ~/.synotools/credentials:
Windows users:
Use C:\Users\<YourUsername>\.synotools\credentials.txt instead.
# Device access credentials
SYNOLOGY_IP=your-ip
SYNOLOGY_PORT=your-port
SYNOLOGY_USERNAME=your-username
SYNOLOGY_PASSWORD=your-password
# Deluge service credentials
DELUGE_IP=deluge-ip
DELUGE_PORT=deluge-port
DELUGE_USERNAME=deluge-username
DELUGE_PASSWORD=deluge-password
# VPN settings
VPN_ID=vpn-config-id
VPN_NAME=vpn-config-name
VPN_PROTOCOL=vpn-protocol
A list of all fields can be found on env.sample, and this file can be used as a template for your credentials. Once populated and after completing setup you will be able to run commands:
python <installation-folder>/commands/<command-name> <args>Read the Using the tools section for more information about available commands!
Valid credentials are expected to be stored locally, allowing the tools to connect to the device via local network. Fill in the following credentials in your credentials file:
- IP: E.g.
192.168.1.35 - Port:
5000for http, or5001for https - Username: Same username you normally use to log in through the web interface
- Password: Corresponding password
Finding out your local IP will depend on your OS, router configuration and other factors. Please refer to DSM's User Guide for more details on how to get or set your device's IP. It is strongly recommended to set a static IP to your NAS, so that the commands and SSH access works reliably without the need to update IP.
Note: Fore security reasons remember not share your personal credentials file or password! Do not commit to repository, or share it with anybody. That file should be private and stored safely, locally.
synotools uses fabric (built in top of paramiko) to handle SSH connections. Certain assumptions are made regarding credentials configurations and SSH keys. It is recommended to set up a SSH Key in your default SO's SSH location. This guide, although focused on GitHub, can assist. Make sure to store the private key in your default location (~/.ssh for Unix systems), and make a note of your public key contents or location, as it will be required for the next step.
By default terminal access is disabled in your device. Enable it as described in the official support.
Then, the public key needs to be added to authorized_keys in your device, and correct permissions set. This handy guide may help.
The download command uses Deluge remotely, so it has to be installed and configured before attempting.
1- Download and install Synocomunity.
2- Deluge's auth config has to include a user, password and permission level that will be used to connect remotely.
3- Deluge server's host ip and port. Defaulted to 127.0.0.1 and 58846 respectively.
4- Once those variables are set, copy them to their relevant fields in your credentials file.
In order to set up Deluge, you can either:
a) Use Deluge's default username: deluge and password deluge, or
b) Create your own user, as described here.
Note: If a user is going to be created, folders in the NAS are likely to differ compared with the guide above depending on your system. Auth file might be located in /var/packages/deluge/target/var, for instance.
The NAS can connect through a VPN network interface, which needs to be set up first. This document explains the process. Once a VPN profile has been set up and used at least once, VPN configuration may be retrieved from configuration and copied into the credentials file. These details can be obtained from vpnc_last_connect as explained here.
Most commands currently included in the tools are sh scripts expected to be hosted in the NAS, with either sh or python scripts that are run locally. Although most scripts can be run directly from python, a number of .docker scripts have been added so that anything can be run in one command.
This step is necessary before attempting to run any other script, as they rely in the scripts having been installed first!
./install.docker <your-ssh-key-name>
# e.g. ./install.docker paulo_rsa
Gathers all scripts in synotools/scripts, zips them and deploys them to your NAS ~/.scripts folder. User is taken from the credentials file. SSH is required to connect to the NAS without additional authentication.
Note: Adding ssh key to Docker install image means that this image should never be shared publicly (i.e. pushed to Docker repo) for security reasons.
Add a torrent to Deluge in the NAS, downloading it to default download folder.
python synotools/command/download.py "<your-torrent>"
# e.g python synotools/commands/download.py "https://torrents.linuxmint.com/torrents/linuxmint-17-cinnamon-32bit-v2.iso.torrent"
# e.g python synotools/commands/download.py "magnet:?xt=urn:btih:336165b4134e3754fa6996d881a7e7b55a40eb68&dn=archlinux-2019.06.01-x86_64.iso&tr=udp://tracker.archlinux.org:6969&tr=http://tracker.archlinux.org:6969/announce"Check whether NAS is connected through a VPN, and connect if it's not.
python synotools/commands/vpn_connect.pyTested with Synology's DS218j model.
This software has been created and is maintained in Linux Mint, but developers should be able to contribute using practically any Unix platform. Before starting, the following tools will need to be installed and configured:
- Docker
- Git
- Pipenv
There are two types of dependencies:
- Python Packages: Handled automatically thanks to
pipandpipenv. Both the core and development dependencies are included in the project'sPipfile. - Other Dependencies: In order to prevent the developers' system from cluttering, all external dependencies that are not installable with package managers are supposed to sit in the
dependenciesfolder. Scripts are provided to install these automatically.
1- Clone the base repository on a location of your choice.
git clone [email protected]:DazEdword/synology-toolset.git
2- Configure your credentials file and ssh keys as explained in the Getting Started section.
3- Ensure all scripts are executable.
make permissions
Several Docker scripts have been set up to unambiguously run a subset of tests, while taking care of all required dependencies. Using these scripts Docker should handle everything for you:
# Unit tests
make test/unit# Scripts tests (bash unit tests)
make test/scripts# Integration tests
make test/integrationAlternatively, a virtual environment could be created and all dependencies installed via scripts, allowing for richer test runs as covered in pytest's documentation.
Note: Integration tests may require your NAS to be on and available in your local network in order to pass, as tests could be directly interacting with it.