using.rst
1 .. _using-main: 2 3 ****************************** 4 Using Reticulum on Your System 5 ****************************** 6 7 Reticulum is not installed as a driver or kernel module, as one might expect 8 of a networking stack. Instead, Reticulum is distributed as a Python module, 9 containing the networking core, and a set of utility and daemon programs. 10 11 This means that no special privileges are required to install or use it. It 12 is also very light-weight, and easy to transfer to, and install on new systems. 13 14 When you have Reticulum installed, any program or application that uses Reticulum 15 will automatically load and initialise Reticulum when it starts, if it is not 16 already running. 17 18 In many cases, this approach is sufficient. When any program needs to use 19 Reticulum, it is loaded, initialised, interfaces are brought up, and the 20 program can now communicate over any Reticulum networks available. If another 21 program starts up and also wants access to the same Reticulum network, the already 22 running instance is simply shared. This works for any number of programs running 23 concurrently, and is very easy to use, but depending on your use case, there 24 are other options. 25 26 Configuration & Data 27 -------------------- 28 29 Reticulum stores all information that it needs to function in a single file-system 30 directory. When Reticulum is started, it will look for a valid configuration 31 directory in the following places: 32 33 - ``/etc/reticulum`` 34 - ``~/.config/reticulum`` 35 - ``~/.reticulum`` 36 37 If no existing configuration directory is found, the directory ``~/.reticulum`` 38 is created, and the default configuration will be automatically created here. 39 You can move it to one of the other locations if you wish. 40 41 It is also possible to use completely arbitrary configuration directories by 42 specifying the relevant command-line parameters when running Reticulum-based 43 programs. You can also run multiple separate Reticulum instances on the same 44 physical system, either in isolation from each other, or connected together. 45 46 In most cases, a single physical system will only need to run one Reticulum 47 instance. This can either be launched at boot, as a system service, or simply 48 be brought up when a program needs it. In either case, any number of programs 49 running on the same system will automatically share the same Reticulum instance, 50 if the configuration allows for it, which it does by default. 51 52 The entire configuration of Reticulum is found in the ``~/.reticulum/config`` 53 file. When Reticulum is first started on a new system, a basic, but fully functional 54 configuration file is created. The default configuration looks like this: 55 56 .. code:: ini 57 58 # This is the default Reticulum config file. 59 # You should probably edit it to include any additional, 60 # interfaces and settings you might need. 61 62 # Only the most basic options are included in this default 63 # configuration. To see a more verbose, and much longer, 64 # configuration example, you can run the command: 65 # rnsd --exampleconfig 66 67 68 [reticulum] 69 70 # If you enable Transport, your system will route traffic 71 # for other peers, pass announces and serve path requests. 72 # This should be done for systems that are suited to act 73 # as transport nodes, ie. if they are stationary and 74 # always-on. This directive is optional and can be removed 75 # for brevity. 76 77 enable_transport = No 78 79 80 # By default, the first program to launch the Reticulum 81 # Network Stack will create a shared instance, that other 82 # programs can communicate with. Only the shared instance 83 # opens all the configured interfaces directly, and other 84 # local programs communicate with the shared instance over 85 # a local socket. This is completely transparent to the 86 # user, and should generally be turned on. This directive 87 # is optional and can be removed for brevity. 88 89 share_instance = Yes 90 91 92 # If you want to run multiple *different* shared instances 93 # on the same system, you will need to specify different 94 # instance names for each. On platforms supporting domain 95 # sockets, this can be done with the instance_name option: 96 97 instance_name = default 98 99 # Some platforms don't support domain sockets, and if that 100 # is the case, you can isolate different instances by 101 # specifying a unique set of ports for each: 102 103 # shared_instance_port = 37428 104 # instance_control_port = 37429 105 106 107 # If you want to explicitly use TCP for shared instance 108 # communication, instead of domain sockets, this is also 109 # possible, by using the following option: 110 111 # shared_instance_type = tcp 112 113 114 # On systems where running instances may not have access 115 # to the same shared Reticulum configuration directory, 116 # it is still possible to allow full interactivity for 117 # running instances, by manually specifying a shared RPC 118 # key. In almost all cases, this option is not needed, but 119 # it can be useful on operating systems such as Android. 120 # The key must be specified as bytes in hexadecimal. 121 122 # rpc_key = e5c032d3ec4e64a6aca9927ba8ab73336780f6d71790 123 124 125 # It is possible to allow remote management of Reticulum 126 # systems using the various built-in utilities, such as 127 # rnstatus and rnpath. You will need to specify one or 128 # more Reticulum Identity hashes for authenticating the 129 # queries from client programs. For this purpose, you can 130 # use existing identity files, or generate new ones with 131 # the rnid utility. 132 133 # enable_remote_management = yes 134 # remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b5af27bca1776dc 135 136 137 # You can configure Reticulum to panic and forcibly close 138 # if an unrecoverable interface error occurs, such as the 139 # hardware device for an interface disappearing. This is 140 # an optional directive, and can be left out for brevity. 141 # This behaviour is disabled by default. 142 143 # panic_on_interface_error = No 144 145 146 # When Transport is enabled, it is possible to allow the 147 # Transport Instance to respond to probe requests from 148 # the rnprobe utility. This can be a useful tool to test 149 # connectivity. When this option is enabled, the probe 150 # destination will be generated from the Identity of the 151 # Transport Instance, and printed to the log at startup. 152 # Optional, and disabled by default. 153 154 # respond_to_probes = No 155 156 157 [logging] 158 # Valid log levels are 0 through 7: 159 # 0: Log only critical information 160 # 1: Log errors and lower log levels 161 # 2: Log warnings and lower log levels 162 # 3: Log notices and lower log levels 163 # 4: Log info and lower (this is the default) 164 # 5: Verbose logging 165 # 6: Debug logging 166 # 7: Extreme logging 167 168 loglevel = 4 169 170 171 # The interfaces section defines the physical and virtual 172 # interfaces Reticulum will use to communicate on. This 173 # section will contain examples for a variety of interface 174 # types. You can modify these or use them as a basis for 175 # your own config, or simply remove the unused ones. 176 177 [interfaces] 178 179 # This interface enables communication with other 180 # link-local Reticulum nodes over UDP. It does not 181 # need any functional IP infrastructure like routers 182 # or DHCP servers, but will require that at least link- 183 # local IPv6 is enabled in your operating system, which 184 # should be enabled by default in almost any OS. See 185 # the Reticulum Manual for more configuration options. 186 187 [[Default Interface]] 188 type = AutoInterface 189 interface_enabled = True 190 191 If Reticulum infrastructure already exists locally, you probably don't need to 192 change anything, and you may already be connected to a wider network. If not, 193 you will probably need to add relevant *interfaces* to the configuration, in 194 order to communicate with other systems. 195 196 You can generate a much more verbose configuration example by running the command: 197 198 ``rnsd --exampleconfig`` 199 200 The output includes examples for most interface types supported 201 by Reticulum, along with additional options and configuration parameters. 202 203 It is a good idea to read the comments and explanations in the above default config. 204 It will teach you the basic concepts you need to understand to configure your network. 205 Once you have done that, take a look at the :ref:`Interfaces<interfaces-main>` chapter 206 of this manual. 207 208 Included Utility Programs 209 ------------------------- 210 211 Reticulum includes a range of useful utilities, both for managing your Reticulum 212 networks, and for carrying out common tasks over Reticulum networks, such as 213 transferring files to remote systems, and executing commands and programs remotely. 214 215 If you often use Reticulum from several different programs, or simply want 216 Reticulum to stay available all the time, for example if you are hosting 217 a transport node, you might want to run Reticulum as a separate service that 218 other programs, applications and services can utilise. 219 220 The rnsd Utility 221 ================ 222 223 It is very easy to run Reticulum as a service. Simply run the included ``rnsd`` command. 224 When ``rnsd`` is running, it will keep all configured interfaces open, handle transport if 225 it is enabled, and allow any other programs to immediately utilise the 226 Reticulum network it is configured for. 227 228 You can even run multiple instances of ``rnsd`` with different configurations on 229 the same system. 230 231 **Usage Examples** 232 233 Run ``rnsd``: 234 235 .. code:: text 236 237 $ rnsd 238 239 [2023-08-18 17:59:56] [Notice] Started rnsd version 0.5.8 240 241 Run ``rnsd`` in service mode, ensuring all logging output is sent directly to file: 242 243 .. code:: text 244 245 $ rnsd -s 246 247 Generate a verbose and detailed configuration example, with explanations of all the 248 various configuration options, and interface configuration examples: 249 250 .. code:: text 251 252 $ rnsd --exampleconfig 253 254 **All Command-Line Options** 255 256 .. code:: text 257 258 usage: rnsd.py [-h] [--config CONFIG] [-v] [-q] [-s] [--exampleconfig] [--version] 259 260 Reticulum Network Stack Daemon 261 262 options: 263 -h, --help show this help message and exit 264 --config CONFIG path to alternative Reticulum config directory 265 -v, --verbose 266 -q, --quiet 267 -s, --service rnsd is running as a service and should log to file 268 -i, --interactive drop into interactive shell after initialisation 269 --exampleconfig print verbose configuration example to stdout and exit 270 --version show program's version number and exit 271 272 You can easily add ``rnsd`` as an always-on service by :ref:`configuring a service<using-systemd>`. 273 274 The rnstatus Utility 275 ==================== 276 277 Using the ``rnstatus`` utility, you can view the status of configured Reticulum 278 interfaces, similar to the ``ifconfig`` program. 279 280 **Usage Examples** 281 282 Run ``rnstatus``: 283 284 .. code:: text 285 286 $ rnstatus 287 288 Shared Instance[37428] 289 Status : Up 290 Serving : 1 program 291 Rate : 1.00 Gbps 292 Traffic : 83.13 KB↑ 293 86.10 KB↓ 294 295 AutoInterface[Local] 296 Status : Up 297 Mode : Full 298 Rate : 10.00 Mbps 299 Peers : 1 reachable 300 Traffic : 63.23 KB↑ 301 80.17 KB↓ 302 303 TCPInterface[RNS Testnet Dublin/dublin.connect.reticulum.network:4965] 304 Status : Up 305 Mode : Full 306 Rate : 10.00 Mbps 307 Traffic : 187.27 KB↑ 308 74.17 KB↓ 309 310 RNodeInterface[RNode UHF] 311 Status : Up 312 Mode : Access Point 313 Rate : 1.30 kbps 314 Access : 64-bit IFAC by <…e702c42ba8> 315 Traffic : 8.49 KB↑ 316 9.23 KB↓ 317 318 Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running 319 320 Filter output to only show some interfaces: 321 322 .. code:: text 323 324 $ rnstatus rnode 325 326 RNodeInterface[RNode UHF] 327 Status : Up 328 Mode : Access Point 329 Rate : 1.30 kbps 330 Access : 64-bit IFAC by <…e702c42ba8> 331 Traffic : 8.49 KB↑ 332 9.23 KB↓ 333 334 Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running 335 336 **All Command-Line Options** 337 338 .. code:: text 339 340 usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-A] 341 [-l] [-t] [-s SORT] [-r] [-j] [-R hash] [-i path] 342 [-w seconds] [-d] [-D] [-m] [-I seconds] [-v] [filter] 343 344 Reticulum Network Stack Status 345 346 positional arguments: 347 filter only display interfaces with names including filter 348 349 options: 350 -h, --help show this help message and exit 351 --config CONFIG path to alternative Reticulum config directory 352 --version show program's version number and exit 353 -a, --all show all interfaces 354 -A, --announce-stats show announce stats 355 -l, --link-stats show link stats 356 -t, --totals display traffic totals 357 -s, --sort SORT sort interfaces by [rate, traffic, rx, tx, rxs, txs, 358 announces, arx, atx, held] 359 -r, --reverse reverse sorting 360 -j, --json output in JSON format 361 -R hash transport identity hash of remote instance to get status from 362 -i path path to identity used for remote management 363 -w seconds timeout before giving up on remote queries 364 -d, --discovered list discovered interfaces 365 -D show details and config entries for discovered interfaces 366 -m, --monitor continuously monitor status 367 -I, --monitor-interval seconds 368 refresh interval for monitor mode (default: 1) 369 -v, --verbose 370 371 372 .. note:: 373 When using ``-R`` to query a remote transport instance, you must also specify ``-i`` with the path to a management identity file that is authorized for remote management on the target system. 374 375 The rnid Utility 376 ==================== 377 378 With the ``rnid`` utility, you can generate, manage and view Reticulum Identities. 379 The program can also calculate Destination hashes, and perform encryption and 380 decryption of files. 381 382 Using ``rnid``, it is possible to asymmetrically encrypt files and information for 383 any Reticulum destination hash, and also to create and verify cryptographic signatures. 384 385 **Usage Examples** 386 387 Generate a new Identity: 388 389 .. code:: text 390 391 $ rnid -g ./new_identity 392 393 Display Identity key information: 394 395 .. code:: text 396 397 $ rnid -i ./new_identity -p 398 399 Loaded Identity <984b74a3f768bef236af4371e6f248cd> from new_id 400 Public Key : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e 401 Private Key : Hidden 402 403 Encrypt a file for an LXMF user: 404 405 .. code:: text 406 407 $ rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt 408 409 Recalled Identity <bc7291552be7a58f361522990465165c> for destination <8dd57a738226809646089335a6b03695> 410 Encrypting my_file.txt 411 File my_file.txt encrypted for <bc7291552be7a58f361522990465165c> to my_file.txt.rfe 412 413 If the Identity for the destination is not already known, you can fetch it from the network by using the ``-R`` command-line option: 414 415 .. code:: text 416 417 $ rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt 418 419 Requesting unknown Identity for <30602def3b3506a28ed33db6f60cc6c9>... 420 Received Identity <2b489d06eaf7c543808c76a5332a447d> for destination <30602def3b3506a28ed33db6f60cc6c9> from the network 421 Encrypting my_file.txt 422 File my_file.txt encrypted for <2b489d06eaf7c543808c76a5332a447d> to my_file.txt.rfe 423 424 Decrypt a file using the Reticulum Identity it was encrypted for: 425 426 .. code:: text 427 428 $ rnid -i ./my_identity -d my_file.txt.rfe 429 430 Loaded Identity <2225fdeecaf6e2db4556c3c2d7637294> from ./my_identity 431 Decrypting ./my_file.txt.rfe... 432 File ./my_file.txt.rfe decrypted with <2225fdeecaf6e2db4556c3c2d7637294> to ./my_file.txt 433 434 **All Command-Line Options** 435 436 .. code:: text 437 438 usage: rnid.py [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects] 439 [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path] 440 [-f] [-R] [-t seconds] [-p] [-P] [--version] 441 442 Reticulum Identity & Encryption Utility 443 444 options: 445 -h, --help show this help message and exit 446 --config path path to alternative Reticulum config directory 447 -i, --identity identity 448 hexadecimal Reticulum identity or destination hash, or path to Identity file 449 -g, --generate file generate a new Identity 450 -m, --import identity_data 451 import Reticulum identity in hex, base32 or base64 format 452 -x, --export export identity to hex, base32 or base64 format 453 -v, --verbose increase verbosity 454 -q, --quiet decrease verbosity 455 -a, --announce aspects 456 announce a destination based on this Identity 457 -H, --hash aspects show destination hashes for other aspects for this Identity 458 -e, --encrypt file encrypt file 459 -d, --decrypt file decrypt file 460 -s, --sign path sign file 461 -V, --validate path validate signature 462 -r, --read file input file path 463 -w, --write file output file path 464 -f, --force write output even if it overwrites existing files 465 -R, --request request unknown Identities from the network 466 -t seconds identity request timeout before giving up 467 -p, --print-identity print identity info and exit 468 -P, --print-private allow displaying private keys 469 -b, --base64 Use base64-encoded input and output 470 -B, --base32 Use base32-encoded input and output 471 --version show program's version number and exit 472 473 .. _utility-rnpath: 474 475 The rnpath Utility 476 ==================== 477 478 With the ``rnpath`` utility, you can look up and view paths for 479 destinations on the Reticulum network. 480 481 **Usage Examples** 482 483 Resolve path to a destination: 484 485 .. code:: text 486 487 $ rnpath c89b4da064bf66d280f0e4d8abfd9806 488 489 Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/dublin.connect.reticulum.network:4965] 490 491 **All Command-Line Options** 492 493 .. code:: text 494 495 usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-m hops] [-r] [-d] [-D] 496 [-x] [-w seconds] [-R hash] [-i path] [-W seconds] [-b] [-B] [-U] 497 [--duration DURATION] [--reason REASON] [-p] [-j] [-v] 498 [destination] [list_filter] 499 500 Reticulum Path Management Utility 501 502 positional arguments: 503 destination hexadecimal hash of the destination 504 list_filter filter for remote blackhole list view 505 506 options: 507 -h, --help show this help message and exit 508 --config CONFIG path to alternative Reticulum config directory 509 --version show program's version number and exit 510 -t, --table show all known paths 511 -m, --max hops maximum hops to filter path table by 512 -r, --rates show announce rate info 513 -d, --drop remove the path to a destination 514 -D, --drop-announces drop all queued announces 515 -x, --drop-via drop all paths via specified transport instance 516 -w seconds timeout before giving up 517 -R hash transport identity hash of remote instance to manage 518 -i path path to identity used for remote management 519 -W seconds timeout before giving up on remote queries 520 -b, --blackholed list blackholed identities 521 -B, --blackhole blackhole identity 522 -U, --unblackhole unblackhole identity 523 --duration DURATION duration of blackhole enforcement in hours 524 --reason REASON reason for blackholing identity 525 -p, --blackholed-list 526 view published blackhole list for remote transport instance 527 -j, --json output in JSON format 528 -v, --verbose 529 530 531 The rnprobe Utility 532 ==================== 533 534 The ``rnprobe`` utility lets you probe a destination for connectivity, similar 535 to the ``ping`` program. Please note that probes will only be answered if the 536 specified destination is configured to send proofs for received packets. Many 537 destinations will not have this option enabled, so most destinations will not 538 be probable. 539 540 You can enable a probe-reply destination on Reticulum Transport Instances by 541 setting the ``respond_to_probes`` configuration directive. Reticulum will then 542 print the probe destination to the log on Transport Instance startup. 543 544 **Usage Examples** 545 546 Probe a destination: 547 548 .. code:: text 549 550 $ rnprobe rnstransport.probe 2d03725b327348980d570f739a3a5708 551 552 Sent 16 byte probe to <2d03725b327348980d570f739a3a5708> 553 Valid reply received from <2d03725b327348980d570f739a3a5708> 554 Round-trip time is 38.469 milliseconds over 2 hops 555 556 Send a larger probe: 557 558 .. code:: text 559 560 $ rnprobe rnstransport.probe 2d03725b327348980d570f739a3a5708 -s 256 561 562 Sent 16 byte probe to <2d03725b327348980d570f739a3a5708> 563 Valid reply received from <2d03725b327348980d570f739a3a5708> 564 Round-trip time is 38.781 milliseconds over 2 hops 565 566 If the interface that receives the probe replies supports reporting radio 567 parameters such as **RSSI** and **SNR**, the ``rnprobe`` utility will print 568 these as part of the result as well. 569 570 .. code:: text 571 572 $ rnprobe rnstransport.probe e7536ee90bd4a440e130490b87a25124 573 574 Sent 16 byte probe to <e7536ee90bd4a440e130490b87a25124> 575 Valid reply received from <e7536ee90bd4a440e130490b87a25124> 576 Round-trip time is 1.809 seconds over 1 hop [RSSI -73 dBm] [SNR 12.0 dB] 577 578 **All Command-Line Options** 579 580 .. code:: text 581 582 usage: rnprobe [-h] [--config CONFIG] [-s SIZE] [-n PROBES] 583 [-t seconds] [-w seconds] [--version] [-v] 584 [full_name] [destination_hash] 585 586 Reticulum Probe Utility 587 588 positional arguments: 589 full_name full destination name in dotted notation 590 destination_hash hexadecimal hash of the destination 591 592 options: 593 -h, --help show this help message and exit 594 --config CONFIG path to alternative Reticulum config directory 595 -s SIZE, --size SIZE size of probe packet payload in bytes 596 -n PROBES, --probes PROBES 597 number of probes to send 598 -t seconds, --timeout seconds 599 timeout before giving up 600 -w seconds, --wait seconds 601 time between each probe 602 --version show program's version number and exit 603 -v, --verbose 604 605 606 The rncp Utility 607 ================ 608 609 The ``rncp`` utility is a simple file transfer tool. Using it, you can transfer 610 files through Reticulum. 611 612 **Usage Examples** 613 614 Run rncp on the receiving system, specifying which identities are allowed to send files: 615 616 .. code:: text 617 618 $ rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62 619 620 You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities 621 and simply running the program in listener mode: 622 623 .. code:: text 624 625 $ rncp --listen 626 627 From another system, copy a file to the receiving system: 628 629 .. code:: text 630 631 $ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e 632 633 Or fetch a file from the remote system: 634 635 .. code:: text 636 637 $ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e 638 639 The default identity file is stored in ``~/.reticulum/identities/rncp``, but you can use 640 another one, which will be created if it does not already exist 641 642 .. code:: text 643 644 $ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e -i /path/to/identity 645 646 **All Command-Line Options** 647 648 .. code:: text 649 650 usage: rncp [-h] [--config path] [-v] [-q] [-S] [-l] [-F] [-f] 651 [-j path] [-b seconds] [-a allowed_hash] [-n] [-p] 652 [-i identity] [-w seconds] [--version] [file] [destination] 653 654 Reticulum File Transfer Utility 655 656 positional arguments: 657 file file to be transferred 658 destination hexadecimal hash of the receiver 659 660 options: 661 -h, --help show this help message and exit 662 --config path path to alternative Reticulum config directory 663 -v, --verbose increase verbosity 664 -q, --quiet decrease verbosity 665 -S, --silent disable transfer progress output 666 -l, --listen listen for incoming transfer requests 667 -C, --no-compress disable automatic compression 668 -F, --allow-fetch allow authenticated clients to fetch files 669 -f, --fetch fetch file from remote listener instead of sending 670 -j, --jail path restrict fetch requests to specified path 671 -s, --save path save received files in specified path 672 -O, --overwrite Allow overwriting received files, instead of adding postfix 673 -b seconds announce interval, 0 to only announce at startup 674 -a allowed_hash allow this identity (or add in ~/.rncp/allowed_identities) 675 -n, --no-auth accept requests from anyone 676 -p, --print-identity print identity and destination info and exit 677 -i identity path to identity to use 678 -w seconds sender timeout before giving up 679 -P, --phy-rates display physical layer transfer rates 680 --version show program's version number and exit 681 682 683 The rnx Utility 684 ================ 685 686 The ``rnx`` utility is a basic remote command execution program. It allows you to 687 execute commands on remote systems over Reticulum, and to view returned command 688 output. For a fully interactive remote shell solution, be sure to also take a look 689 at the `rnsh <https://github.com/acehoss/rnsh>`_ program. 690 691 **Usage Examples** 692 693 Run rnx on the listening system, specifying which identities are allowed to execute commands: 694 695 .. code:: text 696 697 $ rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10 698 699 From another system, run a command on the remote: 700 701 .. code:: text 702 703 $ rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo" 704 705 Or enter the interactive mode pseudo-shell: 706 707 .. code:: text 708 709 $ rnx 7a55144adf826958a9529a3bcf08b149 -x 710 711 The default identity file is stored in ``~/.reticulum/identities/rnx``, but you can use 712 another one, which will be created if it does not already exist 713 714 .. code:: text 715 716 $ rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x 717 718 **All Command-Line Options** 719 720 .. code:: text 721 722 usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-n] [-N] 723 [-d] [-m] [-a allowed_hash] [-w seconds] [-W seconds] [--stdin STDIN] 724 [--stdout STDOUT] [--stderr STDERR] [--version] [destination] [command] 725 726 Reticulum Remote Execution Utility 727 728 positional arguments: 729 destination hexadecimal hash of the listener 730 command command to be execute 731 732 optional arguments: 733 -h, --help show this help message and exit 734 --config path path to alternative Reticulum config directory 735 -v, --verbose increase verbosity 736 -q, --quiet decrease verbosity 737 -p, --print-identity print identity and destination info and exit 738 -l, --listen listen for incoming commands 739 -i identity path to identity to use 740 -x, --interactive enter interactive mode 741 -b, --no-announce don't announce at program start 742 -a allowed_hash accept from this identity 743 -n, --noauth accept files from anyone 744 -N, --noid don't identify to listener 745 -d, --detailed show detailed result output 746 -m mirror exit code of remote command 747 -w seconds connect and request timeout before giving up 748 -W seconds max result download time 749 --stdin STDIN pass input to stdin 750 --stdout STDOUT max size in bytes of returned stdout 751 --stderr STDERR max size in bytes of returned stderr 752 --version show program's version number and exit 753 754 755 The rnodeconf Utility 756 ===================== 757 758 The ``rnodeconf`` utility allows you to inspect and configure existing :ref:`RNodes<rnode-main>`, and 759 to create and provision new :ref:`RNodes<rnode-main>` from any supported hardware devices. 760 761 **All Command-Line Options** 762 763 .. code:: text 764 765 usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] 766 [--fw-url url] [--nocheck] [-e] [-E] [-C] 767 [--baud-flash baud_flash] [-N] [-T] [-b] [-B] [-p] [-D i] 768 [--display-addr byte] [--freq Hz] [--bw Hz] [--txp dBm] 769 [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] 770 [--eeprom-wipe] [-P] [--trust-key hexbytes] [--version] [-f] 771 [-r] [-k] [-S] [-H FIRMWARE_HASH] [--platform platform] 772 [--product product] [--model model] [--hwrev revision] 773 [port] 774 775 RNode Configuration and firmware utility. This program allows you to change 776 various settings and startup modes of RNode. It can also install, flash and 777 update the firmware on supported devices. 778 779 positional arguments: 780 port serial port where RNode is attached 781 782 options: 783 -h, --help show this help message and exit 784 -i, --info Show device info 785 -a, --autoinstall Automatic installation on various supported devices 786 -u, --update Update firmware to the latest version 787 -U, --force-update Update to specified firmware even if version matches or is older than installed version 788 --fw-version version Use a specific firmware version for update or autoinstall 789 --fw-url url Use an alternate firmware download URL 790 --nocheck Don't check for firmware updates online 791 -e, --extract Extract firmware from connected RNode for later use 792 -E, --use-extracted Use the extracted firmware for autoinstallation or update 793 -C, --clear-cache Clear locally cached firmware files 794 --baud-flash baud_flash 795 Set specific baud rate when flashing device. Default is 921600 796 -N, --normal Switch device to normal mode 797 -T, --tnc Switch device to TNC mode 798 -b, --bluetooth-on Turn device bluetooth on 799 -B, --bluetooth-off Turn device bluetooth off 800 -p, --bluetooth-pair Put device into bluetooth pairing mode 801 -D, --display i Set display intensity (0-255) 802 -t, --timeout s Set display timeout in seconds, 0 to disable 803 -R, --rotation rotation 804 Set display rotation, valid values are 0 through 3 805 --display-addr byte Set display address as hex byte (00 - FF) 806 --recondition-display 807 Start display reconditioning 808 --np i Set NeoPixel intensity (0-255) 809 --freq Hz Frequency in Hz for TNC mode 810 --bw Hz Bandwidth in Hz for TNC mode 811 --txp dBm TX power in dBm for TNC mode 812 --sf factor Spreading factor for TNC mode (7 - 12) 813 --cr rate Coding rate for TNC mode (5 - 8) 814 -x, --ia-enable Enable interference avoidance 815 -X, --ia-disable Disable interference avoidance 816 -c, --config Print device configuration 817 --eeprom-backup Backup EEPROM to file 818 --eeprom-dump Dump EEPROM to console 819 --eeprom-wipe Unlock and wipe EEPROM 820 -P, --public Display public part of signing key 821 --trust-key hexbytes Public key to trust for device verification 822 --version Print program version and exit 823 -f, --flash Flash firmware and bootstrap EEPROM 824 -r, --rom Bootstrap EEPROM without flashing firmware 825 -k, --key Generate a new signing key and exit 826 -S, --sign Display public part of signing key 827 -H, --firmware-hash FIRMWARE_HASH 828 Set installed firmware hash 829 --platform platform Platform specification for device bootstrap 830 --product product Product specification for device bootstrap 831 --model model Model code for device bootstrap 832 --hwrev revision Hardware revision for device bootstrap 833 834 835 For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>` 836 section of this manual. 837 838 .. _using-interface_discovery: 839 Discovering Interfaces 840 ---------------------- 841 842 Reticulum includes built-in functionality for discovering connectable interfaces over Reticulum itself. This is particularly useful in situations where you want to do one or more of the following: 843 844 * Discover connectable entrypoints available on the Internet 845 * Find connectable radio access points in the physical world 846 * Maintain connectivity to RNS instances with unknown or changing IP addresses 847 848 Discovered interfaces can be **auto-connected** by Reticulum, which makes it possible to create setups where an arbitrary interface can act simply as a bootstrap connection, that can be torn down again once more suitable interfaces have been discovered and connected. 849 850 The interface discovery mechanism uses announces sent over Reticulum itself, and supports both publicly readable interfaces and private, encrypted discovery, that can only be decoded by specified *network identities*. It is also possible to specify which network identities should be considered valid sources for discovered interfaces, so that interfaces published by unknown entities are ignored. 851 852 .. note:: 853 A *network identity* is a normal Reticulum identity keyset that can be used by 854 one or more transport nodes to identify them as belonging to the same overall 855 network. In the context of interface discovery, this makes it easy to manage 856 connecting to only the particular networks you care about, even if those networks 857 utilize many individual physical transport node. 858 859 This also makes it convenient to auto-connect discovered interfaces only for networks you have some level of trust in. 860 861 For information on how to make your interfaces discoverable, see the :ref:`Discoverable Interfaces<interfaces-discoverable>` chapter of this manual. The current section will focus on how to actually *discover and connect to* interfaces available on the network. 862 863 In its most basic form, enabling interface discovery is as simple as setting ``discover_interfaces`` to ``true`` in your Reticulum config: 864 865 .. code:: text 866 867 [reticulum] 868 ... 869 discover_interfaces = yes 870 ... 871 872 Once this option is enabled, your RNS instance will start listening for interface discovery announces, and store them for later use or inspection. You can list discovered interfaces with the ``rnstatus`` utility: 873 874 .. code:: text 875 876 $ rnstatus -d 877 878 Name Type Status Last Heard Value Location 879 ------------------------------------------------------------------------- 880 Sideband Hub Backbone ✓ Available 1h ago 16 46.2316, 6.0536 881 RNS Amsterdam Backbone ✓ Available 32m ago 16 52.3865, 4.9037 882 883 884 You can view more detailed information about discovered interfaces, including configuration snippets for pasting directly into your ``[interfaces]`` config, by using the ``rnstatus -D`` option: 885 886 .. code:: text 887 888 $ rnstatus -D sideband 889 890 Transport ID : 521c87a83afb8f29e4455e77930b973b 891 Name : Sideband Hub 892 Type : BackboneInterface 893 Status : Available 894 Transport : Enabled 895 Distance : 2 hops 896 Discovered : 9h and 40m ago 897 Last Heard : 1h and 15m ago 898 Location : 46.2316, 6.0536 899 Address : sideband.connect.reticulum.network:7822 900 Stamp Value : 16 901 902 Configuration Entry: 903 [[Sideband Hub]] 904 type = BackboneInterface 905 enabled = yes 906 remote = sideband.connect.reticulum.network 907 target_port = 7822 908 transport_identity = 521c87a83afb8f29e4455e77930b973b 909 910 In addition to providing local interface discovery information and control, the ``rnstatus`` utility can export discovered interface data in machine-readable JSON format using the ``rnstatus -d --json`` option. This can be useful for exporting the data to external applications such as status pages, access point maps and similar. 911 912 To control what sources are considered valid for discovered sources, additional 913 configuration options can be specified for the interface discovery system. 914 915 * The ``interface_discovery_sources`` option is a list of the network or transport identities from which interfaces will be accepted. If this option is set, all others will be ignored. If this option is not set, discovered interfaces will be accepted from any source, but are still subject to stamp value requirements. 916 917 * The ``required_discovery_value`` options specifies the minimum stamp value required for the interface announce to be considered valid. To make it computationally difficult to spam the network with a large number of defunct or malicious interfaces, each announced interface requires a valid cryptographical stamp, of configurable difficulty value. 918 919 * The ``autoconnect_discovered_interfaces`` value defaults to ``0``, and specifies the maximum number of discovered interfaces that should be auto-connected at any given time. If set to a number greater than ``0``, Reticulum automatically manages discovered interface connections, and will bring discovered interfaces up and down based on availability. You can at any time add discovered interfaces to your configuration manually, to persistently keep them available. 920 921 * The ``network_identity`` option specifies the *network identity* for this RNS instance. This identity is used both to sign (and potentially encrypt) *outgoing* interface discovery announces, and to decrypt incoming discovery information. 922 923 The configuration snippet below contains an example of setting these additional configuration options: 924 925 .. code:: text 926 927 [reticulum] 928 ... 929 discover_interfaces = yes 930 interface_discovery_sources = 521c87a83afb8f29e4455e77930b973b 931 required_discovery_value = 16 932 autoconnect_discovered_interfaces = 3 933 network_identity = ~/.reticulum/storage/identities/my_network 934 ... 935 936 Remote Management 937 ----------------- 938 939 It is possible to allow remote management of Reticulum 940 systems using the various built-in utilities, such as 941 ``rnstatus`` and ``rnpath``. To do so, you will need to set 942 the ``enable_remote_management`` directive in the ``[reticulum]`` 943 section of the configuration file. You will also need to specify 944 one or more Reticulum Identity hashes for authenticating the 945 queries from client programs. For this purpose, you can use 946 existing identity files, or generate new ones with the rnid utility. 947 948 The following is a truncated example of enabling remote management 949 in the Reticulum configuration file: 950 951 .. code:: text 952 953 [reticulum] 954 ... 955 enable_remote_management = yes 956 remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b5af27bca1776dc 957 ... 958 959 For a complete example configuration, you can run ``rnsd --exampleconfig``. 960 961 .. _using-blackhole_management: 962 963 Blackhole Management 964 -------------------- 965 966 Reticulum networks are fundamentally permissionless and open, allowing anyone with a compatible interface to participate. While this openness is essential for a resilient and decentralized network, it also exposes the network to potential abuse, such as peers flooding the network with excessive announce broadcasts or other forms of resource exhaustion. 967 968 The **Blackhole** system provides tools to help manage this problem. It allows operators and individual users to block specific identities at the Transport layer, preventing them from propagating announces through your node, and for other nodes to reach them through your network. 969 970 .. important:: 971 972 There is fundamentally **no way** to *globally* block or censor any identity or destination in Reticulum networks. The blackhole functionality will prevent announces from (and traffic to) all destinations associated with the blackholed identity *on your own network segments only*. 973 974 This provides users and operators with control over what they want to allow *on their own network segments*, but there is no way to globally censor or remove an identity, as long as *someone* is willing to provide transport for it. 975 976 This functionality serves a dual purpose: 977 978 * **For Individual Users:** It offers a simple way to maintain a quiet and efficient local network by manually blocking spammy or unwanted peers. 979 * **For Network Operators:** It enables the creation of federated, community-wide security standards. By publishing and sharing blackhole lists, operators can protect large infrastructures and distribute spam filtering rules across the mesh without manual intervention. 980 981 982 Local Blackhole Management 983 ========================== 984 985 The most immediate way to manage unwanted identities is through manual configuration using the ``rnpath`` utility. This allows you to instantly block or unblock specific identities on your local Transport Instance. 986 987 **Blackholing an Identity** 988 989 To block an identity, use the ``-B`` (or ``--blackhole``) flag followed by the identity hash. You can optionally specify a duration and a reason, which are useful for logging and future reference. 990 991 .. code:: text 992 993 $ rnpath -B 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o 994 995 You can also add a duration (in hours) and a reason: 996 997 .. code:: text 998 999 $ rnpath -B 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o --duration 24 --reason "Excessive announces" 1000 1001 **Lifting Blackholes** 1002 1003 To remove an identity from the blackhole, use the ``-U`` (or ``--unblackhole``) flag: 1004 1005 .. code:: text 1006 1007 $ rnpath -U 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o 1008 1009 **Viewing the Blackhole List** 1010 1011 To see all identities currently blackholed on your local instance, use the ``-b`` (or ``--blackholed``) flag: 1012 1013 .. code:: text 1014 1015 $ rnpath -b 1016 1017 <3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o> blackholed for 23h, 56m (Excessive announces) 1018 <399ea050ce0eed1816c300bcb0840938> blackholed indefinitely (Announce spam) 1019 <d56a4fa02c0a77b3575935aedd90bdb2> blackholed indefinitely (Announce spam) 1020 <2b9ec651326d9bc274119054c70fb75e> blackholed indefinitely (Announce spam) 1021 <1178a8f1fad405bf2ad153bf5036bdfd> blackholed indefinitely (Announce spam) 1022 1023 1024 1025 Automated List Sourcing 1026 ======================= 1027 1028 Manually blocking identities is effective for immediate threats, but maintaining an up-to-date blocklist for a large network is impractical. Reticulum supports **automated list sourcing**, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself. 1029 1030 .. warning:: 1031 **Verify Before Subscribing!** Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services. 1032 1033 When enabled, your Transport Instance will periodically (approximately once per hour) connect to configured sources, retrieve their latest blackhole lists, and automatically merge them into your local blocklist. This provides "set-and-forget" protection for both individual users and large networks. 1034 1035 **Configuration** 1036 1037 To enable automated sourcing, add the ``blackhole_sources`` option to the ``[reticulum]`` section of your configuration file. This option accepts a comma-separated list of Transport Identity hashes that you trust to provide valid blackhole lists. 1038 1039 .. code:: ini 1040 1041 [reticulum] 1042 ... 1043 # Automatically fetch blackhole lists from these trusted sources 1044 blackhole_sources = 521c87a83afb8f29e4455e77930b973b, 68a4aa91ac350c4087564e8a69f84e86 1045 ... 1046 1047 **How It Works** 1048 1049 1. When enabled, the ``BlackholeUpdater`` service runs in the background. 1050 2. For every identity hash listed in ``blackhole_sources``, it attempts to establish a temporary link to its associated``rnstransport.info.blackhole`` destination. 1051 3. It requests the ``/list`` path, which returns a dictionary of blackholed identities and their associated metadata. 1052 4. The received list is merged with your local ``blackholed_identities`` database. 1053 5. The lists are persisted to disk, ensuring they survive restarts. 1054 1055 .. note:: 1056 You can verify the external lists you are subscribed to, and their contents, without importing them by using ``rnpath -p``. See the :ref:`rnpath utility documentation<utility-rnpath>` for details on querying remote blackhole lists. 1057 1058 1059 Publishing Blackhole Lists 1060 ========================== 1061 1062 If you are operating a public gateway, a community hub, or simply wish to share your blackhole list with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to *your* definitions of unwanted traffic. 1063 1064 **Enabling Publishing** 1065 1066 To publish your local blackhole list, enable the ``publish_blackhole`` option in the ``[reticulum]`` section: 1067 1068 .. code:: ini 1069 1070 [reticulum] 1071 ... 1072 publish_blackhole = yes 1073 ... 1074 1075 When this is enabled, your Transport Instance will register a request handler at ``rnstransport.info.blackhole``. Any peer that connects to this destination and requests ``/list`` will receive the complete set of identities currently present in your local blackhole database. 1076 1077 **Federation and Trust** 1078 1079 The blackhole system relies on the trust relationship between the subscriber and the publisher. By subscribing to a source, you are implicitly trusting that source to only block identities that are genuinely detrimental to the network. 1080 1081 As the ecosystem matures, this system is designed to integrate with **Network Identities**. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic. 1082 1083 For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative. 1084 1085 Improving System Configuration 1086 ------------------------------ 1087 1088 If you are setting up a system for permanent use with Reticulum, there is a 1089 few system configuration changes that can make this easier to administrate. 1090 These changes will be detailed here. 1091 1092 1093 Fixed Serial Port Names 1094 ======================= 1095 1096 On a Reticulum instance with several serial port based interfaces, it can be 1097 beneficial to use the fixed device names for the serial ports, instead 1098 of the dynamically allocated shorthands such as ``/dev/ttyUSB0``. Under most 1099 Debian-based distributions, including Ubuntu and Raspberry Pi OS, these nodes 1100 can be found under ``/dev/serial/by-id``. 1101 1102 You can use such a device path directly in place of the numbered shorthands. 1103 Here is an example of a packet radio TNC configured as such: 1104 1105 .. code:: text 1106 1107 [[Packet Radio KISS Interface]] 1108 type = KISSInterface 1109 interface_enabled = True 1110 outgoing = true 1111 port = /dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_43891CKM-if00-port0 1112 speed = 115200 1113 databits = 8 1114 parity = none 1115 stopbits = 1 1116 preamble = 150 1117 txtail = 10 1118 persistence = 200 1119 slottime = 20 1120 1121 Using this methodology avoids potential naming mix-ups where physical devices 1122 might be plugged and unplugged in different orders, or when device name 1123 assignment varies from one boot to another. 1124 1125 .. _using-systemd: 1126 1127 Reticulum as a System Service 1128 ============================= 1129 1130 Instead of starting Reticulum manually, you can install ``rnsd`` as a system 1131 service and have it start automatically at boot. 1132 1133 Systemwide Service 1134 ^^^^^^^^^^^^^^^^^^ 1135 1136 If you installed Reticulum with ``pip``, the ``rnsd`` program will most likely 1137 be located in a user-local installation path only, which means ``systemd`` will not 1138 be able to execute it. In this case, you can simply symlink the ``rnsd`` program 1139 into a directory that is in systemd's path: 1140 1141 .. code:: text 1142 1143 sudo ln -s $(which rnsd) /usr/local/bin/ 1144 1145 You can then create the service file ``/etc/systemd/system/rnsd.service`` with the 1146 following content: 1147 1148 .. code:: text 1149 1150 [Unit] 1151 Description=Reticulum Network Stack Daemon 1152 After=multi-user.target 1153 1154 [Service] 1155 # If you run Reticulum on WiFi devices, 1156 # or other devices that need some extra 1157 # time to initialise, you might want to 1158 # add a short delay before Reticulum is 1159 # started by systemd: 1160 # ExecStartPre=/bin/sleep 10 1161 Type=simple 1162 Restart=always 1163 RestartSec=3 1164 User=USERNAMEHERE 1165 ExecStart=rnsd --service 1166 1167 [Install] 1168 WantedBy=multi-user.target 1169 1170 Be sure to replace ``USERNAMEHERE`` with the user you want to run ``rnsd`` as. 1171 1172 To manually start ``rnsd`` run: 1173 1174 .. code:: text 1175 1176 sudo systemctl start rnsd 1177 1178 If you want to automatically start ``rnsd`` at boot, run: 1179 1180 .. code:: text 1181 1182 sudo systemctl enable rnsd 1183 1184 Userspace Service 1185 ^^^^^^^^^^^^^^^^^ 1186 1187 Alternatively you can use a user systemd service instead of a system wide one. This way the whole setup can be done as a regular user. 1188 Create a user systemd service files ``~/.config/systemd/user/rnsd.service`` with the following content: 1189 1190 .. code:: text 1191 1192 [Unit] 1193 Description=Reticulum Network Stack Daemon 1194 After=default.target 1195 1196 [Service] 1197 # If you run Reticulum on WiFi devices, 1198 # or other devices that need some extra 1199 # time to initialise, you might want to 1200 # add a short delay before Reticulum is 1201 # started by systemd: 1202 # ExecStartPre=/bin/sleep 10 1203 Type=simple 1204 Restart=always 1205 RestartSec=3 1206 ExecStart=RNS_BIN_DIR/rnsd --service 1207 1208 [Install] 1209 WantedBy=default.target 1210 1211 Replace ``RNS_BIN_DIR`` with the path to your Reticulum binary directory (eg. /home/USERNAMEHERE/rns/bin). 1212 1213 Start user service: 1214 1215 .. code:: text 1216 1217 systemctl --user daemon-reload 1218 systemctl --user start rnsd.service 1219 1220 If you want to automatically start ``rnsd`` without having to log in as the USERNAMEHERE, do: 1221 1222 .. code:: text 1223 1224 sudo loginctl enable-linger USERNAMEHERE 1225 systemctl --user enable rnsd.service 1226 1227