tox_profile/README.md

163 lines
6.2 KiB
Markdown
Raw Normal View History

2022-09-21 13:21:48 +02:00
# tox_profile
2022-09-24 04:43:49 +02:00
Read and manipulate tox profile files. It started as a simple script from
<https://stackoverflow.com/questions/30901873/what-format-are-tox-files-stored-in>
2022-10-03 08:44:02 +02:00
```tox_savefile.py``` reads a Tox profile and prints to stderr various
things that it finds. Then can write what it found in JSON/YAML/REPR/PPRINT
to a file. It can also test the nodes in a profile using ```nmap```.
It can also download, select, or test nodes in a ```DHTnode.json``` file.
It can also decrypt a profile, saving the output to a file.
It can also edit a profile, changing a few select fields.
Later it can be extended to edit more crucial fields.
2022-09-24 04:43:49 +02:00
2022-10-02 01:38:28 +02:00
## Usage
Reads a tox profile and prints out information on what's in there to stderr.
2022-10-03 00:29:36 +02:00
Call it with one argument, the filename of the profile for the decrypt, edit
or info commands, or the filename of the nodes file for the nodes command.
2022-10-02 01:38:28 +02:00
2022-10-03 08:44:02 +02:00
4 commands are supported:
2022-10-02 01:38:28 +02:00
1. ```--command decrypt``` decrypts the profile and writes to the result
to stdout
2. ```--command info``` prints info about what's in the Tox profile to stderr
3. ```--command nodes``` assumes you are reading a json nodes file instead of
a profile
2022-10-03 08:44:02 +02:00
4. ```--command edit``` edits the profile and writes to the result
to a file.
2022-10-02 01:38:28 +02:00
```
2022-10-03 03:13:26 +02:00
usage: tox_savefile.py [-h] [--output OUTPUT]
2022-10-03 08:44:02 +02:00
[--command info|decrypt|nodes|edit]
[--info info|repr|yaml|json|pprint|nmap_udp|nmap_tcp]
2022-10-04 13:53:29 +02:00
[--indent INDENT]
[--nodes select_tcp|select_udp|select_version|nmap_tcp|nmap_udp,download]
2022-10-02 01:38:28 +02:00
[--download_nodes_url DOWNLOAD_NODES_URL]
2022-10-04 13:53:29 +02:00
[--edit help|section,num,key,val]
2022-10-03 08:44:02 +02:00
profile
2022-10-02 01:38:28 +02:00
```
Positional arguments:
```
profile tox profile file - may be encrypted
```
Optional arguments:
```
-h, --help show this help message and exit
2022-10-03 08:44:02 +02:00
--command {info,decrypt,nodes,edit}
2022-10-02 01:38:28 +02:00
Action command - default: info
--output OUTPUT Destination for info/decrypt/nodes - defaults to stdout
2022-10-04 13:53:29 +02:00
--info info|repr|yaml|json|pprint|nmap_udp|nmap_tcp (may require nmap)
2022-10-02 01:38:28 +02:00
Format for info command
--indent INDENT Indent for yaml/json/pprint
2022-10-04 13:53:29 +02:00
--nodes select_tcp|select_udp|select_version|nmap_tcp|nmap_udp|download
Action for nodes command (requires jq and nmap)
2022-10-02 01:38:28 +02:00
--download_nodes_url DOWNLOAD_NODES_URL
2022-10-04 13:53:29 +02:00
--edit help|section,num,key,val
2022-10-02 01:38:28 +02:00
```
2022-10-02 05:36:34 +02:00
### --command info
```info``` will output the profile on stdout, or to a file with ```--output```
2022-10-03 00:29:36 +02:00
Choose one of ```{info,repr,yaml,json,pprint,save}```
2022-10-02 05:36:34 +02:00
for the format for info command.
Choose one of ```{nmap_udp,nmap_tcp}```
to run tests using ```nmap``` for the ```DHT``` and ```TCP_RELAY```
sections of the profile. Reguires ```nmap``` and uses ```sudo```.
2022-10-03 00:29:36 +02:00
#### Saving a copy
The code now can generate a saved copy of the profile as it parses the profile.
Use the command ```--command info --info save``` with ```--output```
and a filename, to process the file with info to stderr, and it will
save an copy of the file to the ```--output``` (unencrypted).
It may be shorter than the original profile by up to 512 bytes, as the
original toxic profile is padded at the end with nulls (or maybe in the
decryption).
2022-10-02 05:36:34 +02:00
### --command nodes
Takes a DHTnodes.json file as an argument.
Choose one of ```{select_tcp,select_udp,select_version}```
2022-10-03 00:40:43 +02:00
for ```--nodes``` to select TCP nodes, UDP nodes,
or nodes with the latest version. Requires ```jq```.
2022-10-02 05:36:34 +02:00
2022-10-03 00:40:43 +02:00
Choose one of ```{nmap_tcp,nmap_udp}``` to run tests using ```nmap```
for the ```status_tcp==True``` and ```status_udp==True``` nodes.
Reguires ```nmap``` and uses ```sudo```.
2022-10-02 05:36:34 +02:00
2022-10-04 13:53:29 +02:00
Choose ```download``` to download the nodes from ```--download_nodes_url```
2022-10-02 05:36:34 +02:00
### --command decrypt
2022-10-03 08:44:02 +02:00
Decrypt a profile, with ```--output``` to a filename.
2022-10-02 05:36:34 +02:00
2022-10-03 00:29:36 +02:00
### --command edit
The code now can generate an edited copy of the profile.
2022-10-03 08:44:02 +02:00
Use the command ```--command edit --edit section,num,key,val``` with
2022-10-03 00:29:36 +02:00
```--output``` and a filename, to process the file with info to stderr,
and it will save an copy of the edited file to the
```--output``` file (unencrypted). There's not much editing yet; give
```--command edit --edit help``` to get a list of what Available Sections,
2022-10-03 08:44:02 +02:00
and Supported Quads ```(section,num,key,type)``` that can be edited.
2022-10-03 00:29:36 +02:00
Currently it is:
```
2022-10-03 00:40:43 +02:00
NAME,.,Nick_name,str
STATUSMESSAGE,.,Status_message,str
STATUS,.,Online_status,int
2022-10-03 00:29:36 +02:00
```
2022-10-03 00:40:43 +02:00
The ```num``` field is to accomodate sections that have lists:
* ```.``` is a placeholder for sections that don't have lists.
* ```<int>``` is for the nth element of the list, zero-based.
* ```*``` is for all elements of the list.
2022-10-03 00:29:36 +02:00
2022-09-24 04:43:49 +02:00
## Requirements
If you want to read encrypted profiles, you need to download
toxygen to deal with encrypted tox files, from:
2022-10-01 20:18:56 +02:00
<https://git.plastiras.org/emdee/toxygen_wrapper>
2022-09-24 04:43:49 +02:00
Just put the toxygen/toxygen directory on your PYTHONPATH
You also need to link your libtoxcore.so and libtoxav.so
2022-10-01 20:18:56 +02:00
and libtoxencryptsave.so into ```wrapper/../libs/```
2022-09-24 04:43:49 +02:00
Link all 3 from libtoxcore.so files if you have only libtoxcore.so
If you want to read the GROUPS section, you need Python msgpack:
<https://pypi.org/project/msgpack/>
2022-09-30 22:09:14 +02:00
If you want to write in YAML, you need Python yaml:
<https://pypi.org/project/PyYAML/>
2022-09-24 04:43:49 +02:00
If you have coloredlogs installed it will make use of it:
<https://pypi.org/project/coloredlogs/>
2022-10-03 00:29:36 +02:00
For the ```select``` and ```nmap``` commands, the ```jq``` utility is
required. It's available in most distros, or <https://stedolan.github.io/jq/>
For the ```nmap``` commands, the ```nmap``` utility is
required. It's available in most distros, or <https://nmap.org/>
2022-09-24 04:43:49 +02:00
## Future Directions
2022-10-03 00:29:36 +02:00
This has not been tested on Windwoes, but is should be simple to fix.
2022-09-24 04:43:49 +02:00
Because it's written in Python it is easy to extend to, for example,
rekeying a profile when copying a profile to a new device:
<https://git.plastiras.org/emdee/tox_profile/wiki/MultiDevice-Announcements-POC>
2022-10-02 01:38:28 +02:00
2022-10-04 13:53:29 +02:00
Or you could keep the keypair and synchronize profiles between different
clients: e.g. your could keep your profile from toxic as master,
and copy it over your qtox/toxygen/TriFa profile while preserving their
ToxId keypair.
2022-10-02 10:44:33 +02:00
## Specification
2022-10-02 01:38:28 +02:00
There is a copy of the Tox [spec](https://toktok.ltd/spec.html)
in the repo - it is missing any description of the groups section.