Updates to the readme

This commit is contained in:
QuantumEntangledAndy authored and Andrew committed 2020-10-15 10:59:22 +07:00
1 parent 5baacbeeed
commit 3acd0b4a3c
1 file changed
+166 -56
+166 -56
View File
@@ -2,14 +2,19 @@
![CI](https://github.com/thirtythreeforty/neolink/workflows/CI/badge.svg)
Neolink is a small program that acts as a proxy between Reolink IP cameras and normal RTSP clients.
Certain cameras, such as the Reolink B800, do not implement ONVIF or RTSP, but instead use a proprietary "Baichuan" protocol only compatible with their apps and NVRs (any camera that uses "port 9000" will likely be using this protocol).
Neolink allows you to use NVR software such as Shinobi or Blue Iris to receive video from these cameras instead.
Neolink is a small program that acts as a proxy between Reolink IP cameras and
normal RTSP clients.
Certain cameras, such as the Reolink B800, do not implement ONVIF or RTSP, but
instead use a proprietary "Baichuan" protocol only compatible with their apps
and NVRs (any camera that uses "port 9000" will likely be using this protocol).
Neolink allows you to use NVR software such as Shinobi or Blue Iris to receive
video from these cameras instead.
The Reolink NVR is not required, and the cameras are unmodified.
Your NVR software connects to Neolink, which forwards the video stream from the camera.
Your NVR software connects to Neolink, which forwards the video stream from the
camera.
The Neolink project is not affiliated with Reolink in any way; everything it does has been reverse engineered.
The Neolink project is not affiliated with Reolink in any way; everything it
does has been reverse engineered.
## Supported cameras
@@ -21,7 +26,8 @@ Currently it has been tested on the following cameras:
- E1
- Lumus
Neolink does not support other cameras such as the RLC-420, since they already [provide native RTSP](https://support.reolink.com/hc/en-us/articles/360007010473-How-to-Live-View-Reolink-Cameras-via-VLC-Media-Player).
Neolink does not support other cameras such as the RLC-420, since they already
[provide native RTSP](https://support.reolink.com/hc/en-us/articles/360007010473-How-to-Live-View-Reolink-Cameras-via-VLC-Media-Player).
## Installation
@@ -30,25 +36,33 @@ For now, follow these steps.
### Windows/Linux
1. [Install Gstreamer][gstreamer] from the most recent MSI installer on Windows, or your package manager on Linux.
1. [Install Gstreamer][gstreamer] from the most recent MSI installer on Windows,
or your package manager on Linux.
2. If you are using Windows, add the following to your `PATH` environment variable:
```
%GSTREAMER_1_0_ROOT_X86_64%\bin
```
```
%GSTREAMER_1_0_ROOT_X86_64%\bin
```
Note that if you use Chocolatey to install Gstreamer, it does this automatically.
**Note:** If you use Chocolatey to install Gstreamer, it does this
automatically.
3. Download and extract a [prebuilt binary from continuous integration][ci-download]
(click on the topmost commit for the most recent build).
3. Download and extract a [prebuilt binary from continuous integration][ci-download] (click on the topmost commit for the most recent build).
4. Write a configuration file for your cameras. See the section below.
5. Launch Neolink from a shell, passing your configuration file:
```
neolink --config my_config.toml
```
```bash
neolink --config my_config.toml
```
6. Connect your NVR software to Neolink's RTSP server.
The default URL is `rtsp://127.0.0.1:8554/your_camera_name` if you're running it on the same computer.
The default URL is `rtsp://127.0.0.1:8554/your_camera_name` if you're running
it on the same computer.
If you run it on a different server, you may need to open firewall ports.
See the "Viewing" section below for more troubleshooting.
@@ -60,11 +74,12 @@ neolink --config my_config.toml
A Docker image is also available containing Neolink and all its dependencies.
The image is `thirtythreeforty/neolink`.
Port 8554 is exposed, which is the default listen port.
You must mount a configuration file (see below) into the container at `/etc/neolink.toml`.
You must mount a configuration file (see below) into the container at
`/etc/neolink.toml`.
Here is a sample launch commmand:
```
```bash
docker run \
-p 8554:8554 \
--restart=on-failure \
@@ -72,87 +87,168 @@ docker run \
thirtythreeforty/neolink
```
The Docker image is "best effort" and intended for advanced users; questions about running Docker are outside the scope of Neolink.
The Docker image is "best effort" and intended for advanced users; questions
about running Docker are outside the scope of Neolink.
## Configuration
**Note**: for a more comprehensive setup tutorial, refer to the [Blue Iris setup walkthrough in `docs/`][blue-iris-setup] (which is probably also helpful even with other NVR software).
**Note**: for a more comprehensive setup tutorial, refer to the
[Blue Iris setup walkthrough in `docs/`][blue-iris-setup] (which is probably
also helpful even with other NVR software).
[blue-iris-setup]: docs/Setting%20Up%20Neolink%20For%20Use%20With%20Blue%20Iris.md
Copy and modify the `sample_config.toml` to specify the address, username, and password for each camera (if there is no password, you can omit that line).
Each `[[cameras]]` block creates a new camera; the `name` determines the RTSP path you should connect your client to.
Currently Neolink cannot auto-detect cameras like the official clients do; you must specify their IP addresses directly.
Copy and modify the `sample_config.toml` to specify the address, username, and
password for each camera (if there is no password, you can omit that line).
By default the H265 video format is used. Some cameras, for example E1, provide H264 streams. To use these you must specify `format = "h264"` in the `[[cameras]]` config.
Soon this will be auto-detected, and you will not have to know or care about the format.
Each `[[cameras]]` block creates a new camera; the `name` determines the RTSP
path you should connect your client to.
Currently Neolink cannot auto-detect cameras like the official clients do; you
must specify their IP addresses directly.
By default, the HD stream is available at the RTSP path `/name` or `/name/mainStream`, and the SD stream is available at `/name/subStream`.
You can use only the HD stream by adding `stream = "mainStream"` to the `[[cameras]]` config, or only the SD stream with `stream = "subStream"`.
By default the H265 video format is used. Some cameras, for example E1, provide
H264 streams. To use these you must specify `format = "h264"` in the
`[[cameras]]` config. Soon this will be auto-detected, and you will not have to know or care about
the format.
**Note**: The B400/D400 models only support a single stream at a time, so you must add this line to sections for those cameras.
By default, the HD stream is available at the RTSP path `/name` or
`/name/mainStream`, and the SD stream is available at `/name/subStream`.
You can use only the HD stream by adding `stream = "mainStream"` to the
`[[cameras]]` config, or only the SD stream with `stream = "subStream"`.
**Note**: The B400/D400 models only support a single stream at a time, so you
must add this line to sections for those cameras.
By default Neolink serves on all IP addresses on port 8554.
You can modify this by changing the `bind` and the `bind_port` parameter.
You only need one `bind`/`bind_port` setting at the top of the config file.
You can enable `rtsps` (TLS) by adding a `certificate = "/path/to/pem"` to the top section of the config file. This PEM should contain by the certificate and the key used for the server. If TLS is enabled all connections must use `rtsps`. You can also control client side TLS with the config option `tls_client_auth = "none|request|require"`; in this case the client should present a certificate signed by the server's CA.
You can enable `rtsps` (TLS) by adding a `certificate = "/path/to/pem"` to the
top section of the config file. This PEM should contain by the certificate
and the key used for the server. If TLS is enabled all connections must use
`rtsps`. You can also control client side TLS with the config option
`tls_client_auth = "none|request|require"`; in this case the client should
present a certificate signed by the server's CA.
TLS is disabled by default.
You can password-protect the Neolink server by adding `[[users]]`` sections to the configuration file:
You can password-protect the Neolink server by adding `[[users]]` sections to
the configuration file:
```
[[users]]
name: someone
pass: somepass
```
you also need to add the allowed users into each camera by adding the following to `[[cameras]]`.
you also need to add the allowed users into each camera by adding the following
to `[[cameras]]`.
```
permitted_users = ["someone", "someoneelse"]
```
Anywhere a username is accepted it can take any username or one of the following special values.
Anywhere a username is accepted it can take any username or one of the
following special values.
- `anyone` means any user with a valid user/pass
- `anonymous` means no user/pass required
The default `permitted_users` list is:
- `[ "anonymous"]` if no `[[users]]` were given in the config meaning no authentication required to connect.
- `[ "anyone" ]` if `[[users]]` were provided meaning any authourised users can connect.
You can change the Neolink log level by setting the `RUST_LOG` environment variable (not in the configuration file) to one of `error`, `warn`, `info`, `debug`, or `trace`:
- `[ "anonymous"]` if no `[[users]]` were given in the config meaning no
authentication required to connect.
```
- `[ "anyone" ]` if `[[users]]` were provided meaning any authourised users can
connect.
You can change the Neolink log level by setting the `RUST_LOG` environment
variable (not in the configuration file) to one of `error`, `warn`, `info`,
`debug`, or `trace`:
```sh
set RUST_LOG=debug
```
On Linux:
```
```bash
export RUST_LOG=debug
```
## Viewing
Connect your RTSP client to the stream with the name you provided in the configuration file.
Again, the default URL is `rtsp://127.0.0.1:8554/your_camera_name` if you're running it on the same computer as the client.
Connect your RTSP client to the stream with the name you provided in the
configuration file.
Again, the default URL is `rtsp://127.0.0.1:8554/your_camera_name` if you're
running it on the same computer as the client.
The smaller SD video is `rtsp://127.0.0.1:8554/your_camera_name/subStream`.
4K cameras send large video "key frames" once every few seconds and the client must have a receive buffer large enough to store the entire frame.
If your client's buffer size is configurable (like Blue Iris), ensure it's set to 20MB, which should ensure plenty of headroom.
4K cameras send large video "key frames" once every few seconds and the client
must have a receive buffer large enough to store the entire frame.
If your client's buffer size is configurable (like Blue Iris), ensure it's set
to 20MB, which should ensure plenty of headroom.
## Motion Detection and MQTT
If your camera supports motion detection you can have neolink post MQTT
messages to an MQTT server whenever your camera detects motion. To enable this
add the following to your `[[cameras]]` table in the config toml.
```toml
[cameras.mqtt]
# The address of the mqtt server
server = "127.0.0.1"
# The port of the mqtt server
port = 1883
# Optional: User name and password for mqtt
credentials = ["User4MQTT", "Pass4MQTT"]
# Optional: The servers encryption certificate
# Enabling this WILL turn on encryption
# You cannot use both ca and client_auth
ca = "/path/to/cert"
# Optional: The clients encryption certificate and key
# Enabling this WILL turn on encryption
# You cannot use both ca and client_auth
client_auth = ["/Path/to/client/cert", "/Path/to/client/key"]
```
Each camera creates its own client with the id `Neolink-CameraName` and each
camera in the config needs a mqtt table to enable it.
The topic of the message is:
```mqtt
/neolink/CAMERANAME/status/motion
```
With a message of either `on` for motion detected or `off` for motion no longer
detected.
## Stability
Neolink has had minimal testing, but it seems to be very reliable in multiple users' testing.
Neolink has had minimal testing, but it seems to be very reliable in multiple
users' testing.
The formats of all configuration files and APIs is subject to change as required while it is pre-1.0.
The formats of all configuration files and APIs is subject to change as required
while it is pre-1.0.
## Development
Neolink is written in Rust, and binds to Gstreamer to provide RTSP server functionality.
To compile, ensure you have the Rust compiler, Gstreamer, and gst-rtsp-server installed.
Neolink is written in Rust, and binds to Gstreamer to provide RTSP server
functionality.
To compile, ensure you have the Rust compiler, Gstreamer, and gst-rtsp-server
installed.
Then simply run:
```
```bash
cargo build
```
@@ -160,22 +256,36 @@ from this top directory.
### Baichuan Protocol
The "port 9000" protocol used by Reolink and some Swann cameras is internally referred to as the Baichuan protocol; this is the company based in China that is known internationally as Reolink.
The "port 9000" protocol used by Reolink and some Swann cameras is internally
referred to as the Baichuan protocol; this is the company based in China that
is known internationally as Reolink.
This protocol is a slightly convoluted header-data format, and appears to have
been upgraded several times.
The modern variant uses obfuscated XML commands and sends ordinary H.265 or
H.264 video streams encapsulated in a custom header.
This protocol is a slightly convoluted header-data format, and appears to have been upgraded several times.
The modern variant uses obfuscated XML commands and sends ordinary H.265 or H.264 video streams encapsulated in a custom header.
More details about the on-the-wire protocol will come later.
### Baichuan dissector
A Wireshark dissector is available for the BC wire protocol in the `dissector` directory.
It dissects the BC header and also allows viewing the deobfuscated XML in command messages.
To use it, copy or symlink it into your Wireshark plugin directory; typically this is `~/.local/lib/wireshark/plugins/` under Linux.
A Wireshark dissector is available for the BC wire protocol in the `dissector`
directory.
Currently the dissector does not attempt to decode the Baichuan "extension" messages except `binaryData`.
It dissects the BC header and also allows viewing the deobfuscated XML in
command messages.
To use it, copy or symlink it into your Wireshark plugin directory; typically
this is `~/.local/lib/wireshark/plugins/` under Linux.
Currently the dissector does not attempt to decode the Baichuan "extension"
messages except `binaryData`.
This will change in the future as reverse engineering needs require.
## License
Neolink is free software, released under the GNU Affero General Public License v3.
This means that if you incorporate it into a piece of software available over the network, you must offer that software's source code to your users.
Neolink is free software, released under the GNU Affero General Public License
v3.
This means that if you incorporate it into a piece of software available over
the network, you must offer that software's source code to your users.