# Configuration

The caster is managed through configuration files. All files should be in YAML format (opens new window) and should be located in the same folder as the executable file.

caster.yml - The main configuration file

caster:
  host: yccaster.com
  port: 2101
  identifier: Demo caster
  operator: Hedgehack OU
  nmea: 0
  country: EST
  latitude: 59.44
  longitude: 24.74
  fallback_host: 0.0.0.0
  fallback_port: 0
  misc: ""

networks.yml - List of NTRIP network that should be displayed in the SOURCE TABLE

- identifier: SAPOS
  operator: SAPOS
  authentication: B
  fee: 'Y'
  web-net: 'http://igs.ifag.de/'
  web-str: 'http://igs.ifag.de/'
  web-reg: euref-ip@ifag.de
  misc: ''

# Authorization

By default, YCCaster accepts any valid NTRIP connections. There are several strategies that you may employ to protect your caster.

# File

File strategie depends on 2 files that contain a list of mount points and a list of clients that are allowed to connect to the caster.

To enable it, you should specifile these files in caster.yml

caster:
  host: caster.de
  port: 2101
  identifier: YCCaster v1
  operator: MYNET
  nmea: 0
  country: JPN
  latitude: 10.12
  longitude: 10.12
  fallback_host: 0.0.0.0
  fallback_port: 0
  misc: ''
configuration:
  auth:
  - type: file
    options:
      mount-points: mountpoints.yml
      clients: clients.yml

And create respected files

mountpoints.yml

- mount-point: BCEP00BKG0
  password: 12345
  description:
    identifier: Barcelona
    format: RTCM 3.2
    format-details: 1006(15),1008(15),1013(60),1019,1020,1033(15),1075(1),1085(1),1095(1),1230(15)
    carrier: 2
    nav-system: GPS+GLO+GAL
    network: EUREF
    country: ESP
    latitude: 41.41
    longitude: 2.00
    nmea: 0
    solution: 0
    generator: LEICA GR10
    compr-encryp: none
    authentication: B
    fee: N
    bitrate: 6200
    misc: RGP, Ville de Cannes

clients.yml

- username: myrover
  password: 12345

Now, only NTRIP server and client that are listed will be allowed. You may restrict only server or only client connections, by specifying only one of the files in config.

caster.yml

configuration:
  auth:
  - type: file
    options:
      mount-points: mountpoints.yml

# Http

If you are building something bigger, local files may limit your flexibility. Http starategie will allow implement complex authorization logic. Caster will send http requests to an API and will allow or reject NTRIP connections depending on server responses.

To enable this strategie, specify url of your server endpoint and secret that will confirm that request came from your caster.

caster.yml

configuration:
  auth:
  - type: http
    options:
      url: http://api.mycompany.com/ntrip_auth
      secret: super_secret

When the caster receives a request from the NTRIP server or client, it in turn will send a request API.

Server connection authorization request example:

POST / HTTP/1.1
Host: 127.0.0.1:3000
Content-Length: 170
Accept: application/json
Content-Type: application/json
X-Api-Key: super_secret
Accept-Encoding: gzip

{
   "method":"SOURCE",
   "password":"test",
   "uri":"/Test",
   "http_version":"HTTP/1.0",
   "headers":[
      {
         "name":"User-Agent",
         "value":"NTRIP YCServer"
      }
   ],
   "type":"server",
   "ntrip_version":1
}

Client connection authorization request example:

POST / HTTP/1.1
Host: 127.0.0.1:3000
Content-Length: 203
Accept: application/json
Content-Type: application/json
X-Api-Key: super_secret
Accept-Encoding: gzip

{
   "method":"GET",
   "uri":"/Test",
   "http_version":"HTTP/1.0",
   "headers":[
      {
         "name":"User-Agent",
         "value":"NTRIP YCServer"
      },
      {
         "name":"Authorization",
         "value":"Basic cGFrOjEyMzQ1"
      }
   ],
   "type":"client",
   "ntrip_version":1

Caster will authorize NTRIP connection if it gets 2XX http response code and rejects with any other. In case of server connection, the caster will also expect to receive mount point description in the response body.

{
  "identifier": "Barcelona",
  "format": "RTCM 3.2",
  "format-details": "1006(15),1008(15),1013(60),1019,1020,1033(15),1075(1),1085(1),1095(1),1230(15)",
  "carrier": 2,
  "nav-system": "GPS+GLO+GAL",
  "network": "EUREF",
  "country": "ESP",
  "latitude": 41.41,
  "longitude": 2,
  "nmea": 0,
  "solution": 0,
  "generator": "LEICA GR10",
  "compr-encryp": "none",
  "authentication": "B",
  "fee": "N",
  "bitrate": 6200,
  "misc": "RGP, Ville de Cannes"
}

# Mixed

It's possible to use a mixed authorization strategy. For example, you can list some mount points and clients in text files, and use http for the rest of them.

caster.yml

configuration:
  auth:
  - type: file
    options:
      mount-points: mountpoints.yml
      clients: clients.yml
  - type: http
    options:
      url: http://api.mycompany.com/ntrip_auth
      secret: super_secret

YCCaster will check files first, and if it does not find a match in files, it will send http request.

# Events

Things happen. And YCCaster can report about such events.

Event name	Description
caster-ready	Emits when caster is ready to accept incoming connections.
caster-terminate	Emits when caster get termination signal.
connection-accepted	Emits when incoming TCP connection received.
connection-terminated	Emits when incoming TCP connection terminated.
ntrip-request-accepted	Emits when NTRIP request was authorized.
ntrip-request-rejected	Emits when NTRIP request was rejected.
ntrip-session-started	Emits when NTRIP session was started.
ntrip-session-ended	Emits when NTRIP session was was ended.
ntrip-session-server-data	Emits when data from NTRIP server connection received. Data is encoded in base64.
ntrip-session-client-data	Emits when data from NTRIP client connection received. Data is encoded in base64.
caster-status-10	Emits when every 10 seconds. Valid interval is between 1 and 3600.
ntrip-session-status-25	Emits when every 50 seconds. Valid interval is between 1 and 3600.

Caster events example:

            "headers":[
               {
                  "name":"User-Agent",
                  "value":"NTRIP YCServer"
               }
            ],
            "type":"server",
            "ntrip_version":1
         }
      }
   },
   {
      "name":"ntrip-session-started",
      "timestamp":1621776197,
      "data":{
         "address":"31.153.88.250:48114",
         "started_at":1621776197
      }
   },
   {
      "name":"ntrip-session-ended",
      "timestamp":1621776204,
      "data":{
         "address":"31.153.88.250:48114",
         "started_at":1621776197,
         "ended_at":1621776204,
         "type":"server",
         "name":"Test",
         "bytes_transferred":66560
      }
   },
   {
      "name":"connection-terminated",
      "timestamp":1621776204,
      "data":{
         "address":"31.153.88.250:48114",
         "reason":"session_finished"
      }
   }
]

# File

Events can be saved to local file.

caster.yml

configuration:
  events:
  - type: file
    options:
      path: /var/caster/session.log
      types:
        - caster-ready
        - caster-terminate
        - connection-accepted
        - connection-terminated
        - ntrip-request-accepted
        - ntrip-request-rejected
        - ntrip-session-started
        - ntrip-session-ended

# Http

Or they can be send to remote server via http.

caster.yml

configuration:
  - type: http
    options:
      url: api.youcors.com/v1/session
      secret: super_secret
      interval: 1000
      limit: 100
      types: 
        - caster-ready
        - caster-terminate
        - connection-accepted
        - connection-terminated
        - ntrip-request-accepted
        - ntrip-request-rejected
        - ntrip-session-started
        - ntrip-session-ended

Events are sent in batches when number of events reaches the limit or when the interval has passed. The interval is sets in miliseconds.

# API

YCCaster has a built-in http server that provides several endpoints to monitor NTRIP caster status. By default the server will start on an 8080 port, but you may specify a different port and address. Some of endepoints are protected by X-API-Key header others are open to every request.

caster.yml

configuration:
  api:
    address: 0.0.0.0
    port: 8081
    api-keys:
      - secret

# Endpoints

GET /health

Health endpoint return response code 200 with empty body if caster is up and running and is ready to accept incoming NTRIP connections.

Request example:

GET /health HTTP/1.1
Accept: */*
Host: yccaster.com:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Response example:

HTTP/1.1 200 OK
Server: fasthttp
Date: Wed, 26 May 2021 17:34:17 GMT
Content-Length: 0

GET /status

Status endpoint responds with current caster status.

Request example:

GET /status HTTP/1.1
X-API-Key: secret
Accept: */*
Host: yccaster.com:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Response example:

HTTP/1.1 200 OK
Server: fasthttp
Date: Wed, 26 May 2021 17:39:48 GMT
Content-Type: application/json
Content-Length: 144

{
   "data":{
      "address":"[::]:2101",
      "version":"0.0.14",
      "server_connections":1,
      "client_connections":0,
      "started_at":"2021-05-26T17:33:51.831462217Z"
   }
}

GET /mountpoints

Mount points endpoint return list of active server sessions.

Request example:

GET /mountpoints HTTP/1.1
X-API-Key: secret
Accept: */*
Host: yccaster.com:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Response example:

HTTP/1.1 200 OK
Server: fasthttp
Date: Wed, 26 May 2021 17:43:33 GMT
Content-Type: application/json
Content-Length: 131

{
   "data":[
      {
         "name":"Test",
         "address":"62.228.76.148:49220",
         "bytes_transferred":43008,
         "started_at":"2021-05-26T17:43:29.915470675Z"
      }
   ]
}

GET /clients

Clients endpoint return list of active client sessions.

Request example:

GET /clients HTTP/1.1
X-API-Key: secret
Accept: */*
Host: yccaster.com:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Response example:

HTTP/1.1 200 OK
Server: fasthttp
Date: Wed, 26 May 2021 17:55:25 GMT
Content-Type: application/json
Content-Length: 117

{
   "data":[
      {
         "address":"62.228.76.148:43952",
         "bytes_transferred":53248,
         "started_at":"2021-05-26T17:55:20.798783908Z"
      }
   ]
}

# License key

To run YCCaster in commercial mode, you need to specify a license key. Multiple YCCaster instances may be launched with the same key caster.yml

licence-key: K5UMY-73LLH-BSWFB-55V52

← Quick Start