A Python API wrapper and toolset to interact with Synology NAS devices.
Project description
Synotools
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
fabric
and python.
API requires valid credentials as described in the section below.
Getting Started
Install the package with pip:
python -m pip install synotools
Copy provided env.sample
file as env.private
.
cd <path/to/your/installation/root>
cp .env.sample .env.private
Once you proceed with the setup and populate your env.private
file with your own credentials, 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!
Setup
Credentials
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 the .env.private
file:
- IP: E.g.
192.168.1.35
- Port:
5000
for http, or5001
for 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.
SSH key
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.
Enabling NAS SSH access
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.
Installing Deluge in your NAS
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 .env.private.
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.
Using the tools
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.
NAS script installation
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
Zips all scripts in synotools/scripts
, zips them and deploys them to your NAS ~/.scripts
folder. User is taken from the .env.private
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.
Download torrent
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"
Compatibility
Tested with Synology's DS218j model.
Development
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
Dependencies
There are two types of dependencies:
- Python Packages: Handled automatically thanks to
pip3
. They are included in requirements file,requirements.txt
for the tools themselves, andrequirements-dev
for all peripheric development tools. - 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
dependencies
folder. Scripts are provided to install these automatically.
Development environment setup
1- Clone the base repository on a location of your choice.
git clone git@github.com:DazEdword/synology-toolset.git
2- Configure your .env.private
file and ssh keys as explained in the Getting Started section.
3- Ensure all scripts are executable.
cd </path/to/project/root>
find . -type f -iname "*.sh" -exec chmod +x {} \;
find docker/scripts/ -type f -exec chmod +x {} \;
Running tests
Docker should handle everything for you. Alternatively, a virtual environment could be created and all dependencies installed via scripts.
Python unit tests
Simply execute tests.docker
script in the root, and it will install all dependencies and run the test suite.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for synotools-0.3.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a99756d15701765352e0b9feeeb5cf930e5092d572a305b235f0cbda9feab12e |
|
MD5 | febd8dc98687305a27eb75f6f61b0ce0 |
|
BLAKE2b-256 | 2aa392dad01272e5303e40ddb12fa82956872fdf8651882ac03ad0f6248a4165 |