kel-agent
An agent program for translating between various amateur radio installed programs and WebSockets.
This was built to support https://github.com/k0swe/forester but can be used by any web application
that needs to communicate with amateur radio installed programs.
This currently supports communication with WSJT-X. Planned support includes `rigctld` and Ham Radio
Deluxe for transceiver remote control.
To get started using `kel-agent`, download an appropriate executable from the
[latest release](https://github.com/k0swe/kel-agent/releases/latest). Windows, Mac, Debian/Ubuntu
Linux and Raspberry Pi installers are available.
See the [Running documentation](RUNNING.md) for how to configure, execute and serve `kel-agent`.
## Acknowledgements
The wire logo for `kel-agent` was created by [Freepik](https://www.flaticon.com/authors/freepik)
on [Flaticon](https://www.flaticon.com).
kel-agent-0.4.6/RUNNING.md 0000664 0000000 0000000 00000010032 14251261704 0015030 0 ustar 00root root 0000000 0000000 # Running `kel-agent`
## Running on localhost
In the simplest case, `kel-agent` is running on the same computer as your radio programs and
browser. In this case, you can have `kel-agent` bind to `localhost` which will only allow programs
on the same computer to connect. This is straightforward, safe and the default.
```
$ kel-agent
2020/10/10 18:50:32 kel-agent ready to serve at ws://localhost:8081
```
To use a different port, add the `host` argument.
```
$ kel-agent -host localhost:9988
2020/10/10 20:06:39 kel-agent ready to serve at ws://localhost:9988
```
## Running on another machine
If you want to run your radio programs and `kel-agent` on one computer and your browser on another,
this is possible. There are a couple of approaches. Neither is super easy, which I hope to fix.
NOTE: I do *not* recommend serving this in a way that's exposed to the internet because there is
*no* authentication. If exposed to the internet, anyone could potentially initiate transmissions
with your radio.
### SSH port forwarding
This method is relatively simple and quick to execute, but is more brittle than serving secure
websockets because there is some setup each time you want to use the agent remotely, and
conceptually a little harder. Your remote machine must be running an SSH server for this to work.
On the remote machine with your radio software, run `kel-agent` normally. It can be bound to
`localhost`.
```
$ kel-agent
2020/10/10 18:50:32 kel-agent ready to serve at ws://localhost:8081
```
On the machine with your browser, start a command line and establish an SSH tunnel with port
forwarding:
```
$ ssh -N -L localhost:8081:localhost:8081 radio-pi
```
The first `localhost:8081` means "on this (browser) machine, bind to port 8081 and only expose to
`localhost` so other computers can't use it." The second `localhost:8081` means "once you log into
the remote computer, start forwarding traffic to port 8081 on its (remote) `localhost`." Finally,
`radio-pi` in my example is the remote hostname which is running `kel-agent` and the SSH server.
The command will look like it's not doing anything; just let it run, and the tunnel will stay open.
Now your web application can be configured to connect to `localhost`. Traffic bound for
`localhost:8081` will get securely forwarded to the remote machine. Both the browser and `kel-agent`
think they're talking to local processes, and you won't get mixed content warnings.
### Secure Websocket with TLS
This method needs a little more set up ahead of time, but is easier to use once it's set up.
First, you'll need `kel-agent` to bind to `0.0.0.0` to allow connections from other computers.
Second, due to the mixed content policy which is standard in web browsers, you'll need to specify a
TLS certificate and private key. Eventually I hope to make this easy, but for now you'll need to
follow https://stackoverflow.com/a/60516812/587091. In short,
1. generate a CA key and root certificate, then
2. a server key and certificate signing request with the server's hostname,
3. sign the request to generate the server certificate, then finally
4. install the root certificate in your browser's trusted authorities.
Yeah, I really need to make this easier.
```
$ kel-agent -host 0.0.0.0:8081 -key server.key -cert server.crt
2020/10/10 19:05:39 kel-agent ready to serve at wss://0.0.0.0:8081
```
Once running this way, your web application can be configured to connect directly to the remote
computer.
## Allowed origins
As part of the same-origin policy which is standard in web browsers, `kel-agent` will only accept
browser connections from certain origins (basically, websites). By default, only the website
`https://forester.radio` plus some local developer addresses are allowed to connect to `kel-agent`,
but this can be customized if others develop web applications that use `kel-agent`. I'm happy to
accept pull requests to expand the default list!
```
$ kel-agent -origins "https://forester.radio,https://someother.nifty.app"
2020/10/10 19:18:52 Allowed origins are [https://forester.radio https://someother.nifty.app]
```
kel-agent-0.4.6/VERSION.go 0000664 0000000 0000000 00000000207 14251261704 0015045 0 ustar 00root root 0000000 0000000 package main
// These are filled by `go build --ldflags`
var (
Version = "unknown"
GitCommit = "unknown"
BuildTime = "unknown"
)
kel-agent-0.4.6/architecture.dot 0000664 0000000 0000000 00000001577 14251261704 0016576 0 ustar 00root root 0000000 0000000 digraph {
Internet [ shape=septagon]
subgraph clusterComputer{
label="Computer";
labeljust=l;
style=rounded;
fontsize=10;
subgraph clusterBrowser {
label="Web Browser ";
labeljust=l;
fontsize=10;
color=lightgrey;
Application [label="Web Application"; shape=box]
};
agent [label="kel-agent"; shape=box; style=filled; fillcolor=lightblue]
WSJTX [label="WSJT-X"]
rigctld [label="hamlib\nrigctld"]
HRD;
etc [label="..."];
}
edge [style=bold; dir=none; fontsize=10;]
Internet -> Application
Application -> agent [label=" websocket"]
agent -> WSJTX [label="UDP"]
agent -> rigctld [label="TCP"; style=dotted]
agent -> HRD [label="UDP"; style=dotted]
agent -> etc [style=dotted]
}
kel-agent-0.4.6/architecture.svg 0000664 0000000 0000000 00000012567 14251261704 0016610 0 ustar 00root root 0000000 0000000
kel-agent-0.4.6/assets/ 0000775 0000000 0000000 00000000000 14251261704 0014674 5 ustar 00root root 0000000 0000000 kel-agent-0.4.6/assets/kel-agent.1 0000664 0000000 0000000 00000004041 14251261704 0016624 0 ustar 00root root 0000000 0000000 .TH KEL-AGENT 1
.SH NAME
kel-agent \- translates between amateur radio programs and WebSockets
.SH SYNOPSIS
.B kel-agent
[\fB\-host\fR \fIhost:port\fR]
[\fB\-cert\fR \fIcertfile\fR
\fB\-key\fR \fIkeyfile\fR]
[\fB\-origins\fR \fI"http://origin1"\fR[\fI,"http://origin2"\fR...]]
[\fB\-v\fR]
.SH DESCRIPTION
.B kel-agent
translates between various amateur radio installed programs and WebSockets. This
allows amateur radio web applications to access rig control and digital mode
APIs which are only available over TCP, UDP or by watching local files.
\fIWSJT-X\fR is currently supported, with planned support for \fIrigctld\fR and
\fIHam Radio Deluxe\fR.
.PP
.B kel-agent
was built to support https://github.com/k0swe/forester but can be used by any
web application that needs to communicate with amateur radio installed programs.
.SH OPTIONS
.TP
.BR \-host =\fIhost:port\fR
Set the websocket server hosting address. Default is \fIlocalhost:8081\fR.
.TP
.BR \-cert =\fIcertfile\fR \ \fB\-key\fR =\fIkeyfile\fR
Set the websocket server TLS certificate and private key. These are only
necessary when serving beyond localhost.
.TP
.BR -origins =\fI"http://origin1","http://origin2"\fR
Set which CORS origins (basically, which websites) should be allowed to access
the WebSocket server. Default is \fI"https://forester.radio"\fR plus some
localhost development origins.
.TP
.BR -v
Enable verbose debug logging.
.SH EXAMPLE
When running your web application and browser on the same computer as your
ham radio programs, no \fBkel-agent\fR options are needed. This is
straightforward, safe and the default.
.PP
$ \fBkel-agent\fR
.PP
If a different hosting port than 8081 is required, use the \fB-host\fR option.
.PP
$ \fBkel-agent -host\fR=\fIlocalhost:5001\fR
.PP
It's also possible to run your ham radio programs and \fBkel-agent\fR on one
computer, and your web browser and web app on another. This is more complex to
secure. I refer you to the GitHub repository for up-to-date documentation.
.SH SEE ALSO
\(bu https://github.com/k0swe/kel-agent
\(bu https://github.com/k0swe/forester
kel-agent-0.4.6/assets/license-32918167.pdf 0000664 0000000 0000000 00000123054 14251261704 0017740 0 ustar 00root root 0000000 0000000 %PDF-1.4
1 0 obj
<<
/Title ( L i c e n s e)
/Creator ( w k h t m l t o p d f 0 . 1 2 . 5)
/Producer ( Q t 4 . 8 . 7)
/CreationDate (D:20210522211737Z)
>>
endobj
3 0 obj
<<
/Type /ExtGState
/SA true
/SM 0.02
/ca 1.0
/CA 1.0
/AIS false
/SMask /None>>
endobj
4 0 obj
[/Pattern /DeviceRGB]
endobj
6 0 obj
<<
/Type /XObject
/Subtype /Image
/Width 1588
/Height 234
/BitsPerComponent 8
/ColorSpace /DeviceRGB
/Length 7 0 R
/Filter /DCTDecode
>>
stream
JFIF &""&0-0>>T &""&0-0>>T 4"
kd 4!#4 A xWI1sUh9 ) ÀB wX /:IǗIAJO/0lB˦tj7 9t!N͠ An agent program for translating between various amateur radio installed programs and WebSockets. This was built to support https://github.com/k0swe/forester but can be used by any web application that needs to communicate with amateur radio installed programs.
Improvements to websocket and logging
Integration tests
Dependency updates
Added the ability to send client commands to WSJT-X
WSJT-X listening address fixes
Added flag for selecting a custom config file
Add configuration by file
Fix appstream metadata
Fix flatpak app ID