Metadata-Version: 2.1
Name: synoindexwatcher
Version: 0.11.2
Summary: An automated media-index updater for Synology DiskStations based on inotify and synoindex.
Home-page: https://github.com/letorbi/synoindexwatcher
Author: Torben Haase
Author-email: git@letorbi.com
License: UNKNOWN
Description: # Synoindex Watcher - Automated media index updates
        
        Synoindex Watcher is a media index updater for Synology DiskStations based on inotify and synoindex. It watches the media-folders of your DiskStation an updates the media index every time a file or directory inside the media-folders is created, deleted or changed. It is written in Python and licensed as open-source under the GPL version 3.
        
        The original version was written by Mark Houghton, who [published it in his "codesourcery" blog](https://codesourcery.wordpress.com/2012/11/29/more-on-the-synology-nas-automatically-indexing-new-files/). However, most of the original code has been replaced or rewritten by now.
        
        *This Python package is currently in beta-stage. All planned features are implemented, it is working and used on a number of devices. The only thing that's missing are some automated testing-routines, so there could still be undiscovered bugs.*
        
        ## Features
        
        * **Lightweight** No need to install extra Synology packages
        * **Intelligent** Executes only if a file has actually been added/deleted/renamed
        * **Agnostic** Python 2 and Python 3 compatible (minimum tested version is 2.7)
        
        ## Installation
        
        Synoindex Watcher cannot be installed via Synology's Package Center. You have to log in via SSH and use the terminal.  I recommend to use pip for the installation. Synology DiskStations do not have pip installed by default, but you can add it easily with the following command:
        
        ```
        $ wget https://bootstrap.pypa.io/get-pip.py -qO - | sudo python
        ```
        
        Now you can install the Synoindex Watcher module:
        
        ```
        $ sudo python -m pip install --upgrade synoindexwatcher
        ```
        
        You can use the same command to upgrade Synoindex Watcher from an older version.
        
        This will also install its dependency [inotifyrecursive](https://pypi.org/project/inotifyrecursive/) and also [configparser](https://pypi.org/project/configparser/), if you use Python <= 3.5.
        
        ## Usage
        
        You can start Synoindex Watcher with the following command:
        
        ```
        $ python -m synoindexwatcher
        ```
        
        Synoindex Watcher will watch the directories */volume1/music*, */volume1/photo* and */volume1/video* by default.  You can change this, as well as some other things, by adding some [command-line arguments](#command-line-arguments) or using a [configuration-file](#configuration-file). You can also use an init-script to [start Synoindex Watcher on boot](#start-on-boot).
        
        ### Command-line arguments
        
        The default behaviour of Synoindex Watcher can be changed with various command-line arguments:
        
        * `path [path]`: By appending one or more paths to the command-line you can define which directories shall be watched by synoindexwatcher. For example `python -m synoindexwatcher /home/me/Music` will tell Synoindex Watcher to watch only the directory */home/me/Music*.
        
        * `--blacklist=regex`: Define a regular-expression for a global blacklist. For example `python -m synoindexwatcher --blacklist="foo|bar"` will tell Synoindex Watcher ignore files and directories with `foo` or `bar` in their name. The default regular-expression is `^\.|^\@|\.tmp$`, which means that files and directories are ignored if they start with `.` or `@` or end with `.tmp`. The blacklist is applied after the whitelist.
        
        * `--whitelist=regex`: Define a regular-expression for a global whitelist. For example `python -m synoindexwatcher --whitelist="foo|bar"` will tell Synoindex Watcher to watch only files and directories with `foo` or `bar` in their name. The default regular-expression is empty, which means that all files and directories, which are not blacklisted, are added to the media-index. The whitelist is applied before the blacklist.
        
        * `--logfile=file`: Write log-messages to the specified file. For example `python -m synoindexwatcher --logfile=/home/me/watcher.log` will tell Synoindex Watcher to write into the file */home/me/watcher.log*. By default Synoindex Watcher will write to the terminal, if it is attached to one, or to */var/log/synoindexwatcher.log* otherwise.
        
        * `--loglevel=value`: Synoindex Watcher logs errors, warnings and informational messages by default. You can change this by setting the log-level to either `DEBUG`, `INFO`, `WARNING` or `ERROR`. For example `python -m synoindexwatcher --loglevel=DEBUG` will also log (a lot of) debugging messages along with errors, warnings and infos.
        
        * `--config=file`: Get the default-configuration from a certain file. For example `python -m synoindexwatcher --config=/etc/synoindexwatcher.conf` will tell Synoindex Watcher to use the values in */etc/synoindexwatcher.conf* as its default-values. Any additional command-line arguments will override the values read from the configuration-file.
        
        * `--rebuild-index`: Add all allowed files and directories in the watched directories and exit afterwards. Use it, if your media-index lacks entries for existing files. Read the [related FAQ-entry](#the-media-index-contains-entries-for-files-that-do-not-exist), if you want to remove non-existing files from the media-index.
        
        * `--generate-init`: Generate an init-script, write it to the standard output and exit afterwards. Any additional command-line arguments will be integrated into the generated script. See the [start on boot](#start-on-boot) section above for further details.
        
        * `--generate-config`: Generate a configuration-file, write it to the standard output and exit afterwards. Any additional command-line arguments will be integrated into the generated configuration. See the [configuration-file](#configuration-file) section below for further details.
        
        * `--help`: Write a short online help to the standard output and exit afterwards.
        
        ### Configuration-file
        
        The default behaviour of Synoindex Watcher can also be changed via a configuration-file instead of command-line arguments. Use the following command to create a configuration file:
        
        ```
        python -m synoindexwatcher --generate-config | sudo tee /usr/local/etc/synoindexwatcher.conf
        ```
        
        The generated file is split into several sections: The section `[GLOBAL]` may contain default-values for some [command-line arguments](#command-line-arguments), while each of the other sections (e.g. `[/volume1/music]`) represents a directory that shall be watched. The directory-sections contain no values so far.
        
        You have to explicitly tell Synoindex Watcher to use a configuration-file by calling it like this:
        
        ```
        python -m synoindexwatcher --config=/usr/local/etc/synoindexwatcher.conf
        ```
        
        Keep in mind, that you can use additional command-line arguments to override the values from the configuration-file.
        
        ### Start on boot
        
        Use the following commands to create an init-script that starts Synoindex Watcher in the background when your DiskStation boots:
        
        ```
        $ python -m synoindexwatcher --generate-init | sudo tee /usr/local/etc/rc.d/S99synoindexwatcher.sh
        $ sudo chmod a+x /usr/local/etc/rc.d/S99synoindexwatcher.sh
        ```
        
        Please note that any messages are written into the file */var/log/synoindexwatcher.log*, if Synoindex Watcher is running as a background process. You can use the `--logfile` parameter to write the output to another file.
        
        Also other command-line arguments will be integrated into the init-script. The following line will generate an init-script that tells Synoindex Watcher to watch only the directory */home/me/Music* and to log messages to */home/me/watcher.log*:
        
        ```
        $ python -m synoindexwatcher --generate-init --logfile=/home/me/watcher.log /home/me/Music
        ```
        
        It is recommended to use a configuration file along with the init script, because it allows you to change the behaviour of Synoindex Watcher without the need to regenerate the init-script after every change. Assuming you have created a configuration-file with the commands in the previous section, you can use the following line to generate an init-script that recognizes this file:
        
        ```
        $ python -m synoindexwatcher --generate-init --config=/usr/local/etc/synoindexwatcher.conf
        ```
        
        ## FAQ
        
        ### I'm getting `OSError: [Errno 28] No space left on device`
        
        This actually does not mean that you run out of disk space, but rather that your system does not allow enough inode-watchers to watch all your media files. The message is quite confusing, though.
        
        To fix this temporarily you could simply type `echo 204800 > /proc/sys/fs/inotify/max_user_watches` as root. The maximum number of inode-watchers in the user-space would be 204800 afterwards, which should be enough for most use-cases.  Unfortunately this fixes the problem only until the next reboot.
        
        For a permanent solution it is recommended to add the line `fs.inotify.max_user_watches = 204800` to the file */etc/sysctl.conf*. This should set the maximum value during boot, but I had to add an init-script that executes `sysctl -p /etc/sysctl.conf` to make it work. The simplest way would be to add the command to the start-section of the init-script for Synonindex Watcher.
        
        ### The media-index contains entries for files that do not exist
        
        To get rid of entries for non-existing files in the media-index, you have to clear the whole media-index and repopulate it afterwards. Since this requires to modify the database directly with SQL-commands, *it is strongly recommended to create a backup* before executing the following commands that clear the media-index tables:
        
        ```
        $ sudo synoservice --hard-stop synoindexd
        $ psql mediaserver -tAc "SELECT string_agg(tablename, ',') from pg_catalog.pg_tables WHERE tableowner = 'MediaIndex'"
        $ psql mediaserver -c  "TRUNCATE `psql mediaserver -tAc "SELECT string_agg(tablename, ',') from pg_catalog.pg_tables WHERE tableowner = 'MediaIndex'"` RESTART IDENTITY"
        $ sudo synoservice --start synoindexd"
        
        ```
        Afterwards you can use Synoindex Watcher to repopulate the media-index:
        
        ```
        $ python -m synoindexwatcher --rebuild-index
        ```
        
        Make sure to add additional arguments like `--config` or the paths you want to watch.
        
        ----
        
        Copyright (c) 2019-2020 Torben Haase \<[https://pixelsvsbytes.com](https://pixelsvsbytes.com)>
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Requires-Python: >=2.7, !=3.0.*, !=3.1.*
Description-Content-Type: text/markdown
