prim-ctrl 0.7.13__tar.gz → 0.8.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: prim-ctrl
3
- Version: 0.7.13
3
+ Version: 0.8.0
4
4
  Summary: Primitive Ctrl - Remote control of your phone's Primitive FTPd Android SFTP server and optionally Tailscale VPN.
5
5
  License-Expression: Apache-2.0
6
6
  License-File: LICENSE
@@ -14,7 +14,7 @@ Requires-Dist: aiohttp (>=3.13.2)
14
14
  Requires-Dist: asyncssh (>=2.21.1)
15
15
  Requires-Dist: dnspython (>=2.8.0)
16
16
  Requires-Dist: platformdirs (>=4.5.0)
17
- Requires-Dist: tailscale-fixed (>=0.7.0,<0.8.0)
17
+ Requires-Dist: tailscale (>=0.8.0,<0.9.0)
18
18
  Requires-Dist: zeroconf (>=0.148.0)
19
19
  Project-URL: Change Log, https://github.com/lmagyar/prim-ctrl/blob/main/CHANGELOG.md
20
20
  Description-Content-Type: text/markdown
@@ -28,7 +28,7 @@ Though Primitive FTPd consumes minimal power when it is not used, remote start/s
28
28
 
29
29
  But in case of Tailscale, it is a real battery and mobile network data drain when not used, local and remote start/stop is de facto very useful.
30
30
 
31
- With the help of this script you can sync your phone with eg. your home NAS server whereever your phone is on a WiFi network - or even on cellular. Your phone doesn't have to be on the same LAN to make zeroconf working when you have alternative access through VPN.
31
+ With the help of this script you can sync your phone with eg. your home NAS server whereever your phone is on a WiFi network - or even on cellular. Your phone doesn't have to be on the same WiFi to make zeroconf working when you have alternative access through VPN. But VPN can help even if the phone is on the same WiFi as eg. your laptop, but due to networking restrictions they can't access each other directly (eg. hotel or airport WiFi).
32
32
 
33
33
  See my other project, https://github.com/lmagyar/prim-sync, for bidirectional and unidirectional sync over SFTP (multiplatform Python script optimized for the Primitive FTPd SFTP server).
34
34
 
@@ -138,28 +138,29 @@ But if the script runs scheduled, we can't be sure whether the phone is on WiFi,
138
138
  Notes:
139
139
  - Even when -b option is **not** used, the script will output 'connected=(local|remote)', what you can use to determine whether to use -a option for the prim-sync script
140
140
  - If local Tailscale VPN was disconnected for a longer period (several hours), the public DNS records for Funnel are removed by Tailscale, and after connecting local Tailscale VPN to the tailnet it can take up to 10 minutes for Funnel's public DNS records to show up for your tailnet domain. If the script connects local Tailscale VPN to the tailnet, then it regularly checks and waits up to 10 minutes for the public DNS records to get updated.
141
+ - If you want to interrupt the synchronization, press Ctrl-C once, and wait few seconds until the script properly removes temporary files, saves it's internal state and restores Primitive FTPd and VPN states.
141
142
 
142
143
  ### Some example
143
144
 
144
145
  <details><summary>Ubuntu</summary>
145
146
 
146
147
  ```
147
- prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 tailscale-secretfile -t -i start -b
148
- prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 tailscale-secretfile -t -i stop -r ${PREV_STATE}
148
+ prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net tailscale-secretfile your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 -t -i start -b
149
+ prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net tailscale-secretfile your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 -t -i stop -r ${PREV_STATE}
149
150
  ```
150
151
  </details>
151
152
  <details><summary>Windows</summary>
152
153
 
153
154
  ```
154
- prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 tailscale-secretfile -t -i start -b
155
- prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 tailscale-secretfile -t -i stop -r !PREV_STATE!
155
+ prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net tailscale-secretfile your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 -t -i start -b
156
+ prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net tailscale-secretfile your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 -t -i stop -r !PREV_STATE!
156
157
  ```
157
158
  </details>
158
159
 
159
160
  ### Options
160
161
 
161
162
  ```
162
- usage: prim-ctrl Automate [-h] [-i {test,start,stop}] [-t] [-s] [--debug] [--tailscale tailnet remote-machine-name sftp-port] [--funnel local-machine-name local-port local-path external-port secretfile] [-ac] [-b] [-r STATE]
163
+ usage: prim-ctrl Automate [-h] [-i {test,start,stop}] [-t] [-s] [--debug] [--tailscale tailnet secretfile remote-machine-name sftp-port] [--funnel local-machine-name local-port local-path external-port] [-rv DAYS] [-ac] [-b] [-r STATE]
163
164
  automate-account automate-device automate-tokenfile server-name keyfile
164
165
 
165
166
  Remote control of your phone's Primitive FTPd and optionally Tailscale app statuses via the Automate app, for more details see https://github.com/lmagyar/prim-ctrl
@@ -171,47 +172,47 @@ Note: optionally if your laptop is accessible through Tailscale Funnel then VPN
171
172
  Output: even when -b option is not used, the script will output 'connected=(local|remote)', what you can use to determine whether to use -a option for the prim-sync script
172
173
 
173
174
  positional arguments:
174
- automate-account your Google account email you set up in the Automate flow's 2nd block's (Set variable google_account to...) Value field
175
- automate-device the device name you can see at the Automate flow's Cloud receive block's This device field
176
- automate-tokenfile filename containing Automates's Secret that located under your .secrets folder
177
- (generated on https://llamalab.com/automate/cloud, use the same Google account you set the automate_account option to)
178
- Note: if the account you use to send messages is different from the automate_account option,
179
- set it up in the Automate flow's 3rd block's (Set variable other_managing_accounts to...) Value field
180
- server-name the Servername configuration option from Primitive FTPd app
181
- keyfile private SSH key filename located under your .ssh folder, see the documentation of prim-sync for more details
175
+ automate-account your Google account email you set up in the Automate flow's 2nd block's (Set variable google_account to...) Value field
176
+ automate-device the device name you can see at the Automate flow's Cloud receive block's This device field
177
+ automate-tokenfile filename containing Automates's Secret that located under your .secrets folder
178
+ (generated on https://llamalab.com/automate/cloud, use the same Google account you set the automate_account option to)
179
+ Note: if the account you use to send messages is different from the automate_account option,
180
+ set it up in the Automate flow's 3rd block's (Set variable other_managing_accounts to...) Value field
181
+ server-name the Servername configuration option from Primitive FTPd app
182
+ keyfile private SSH key filename located under your .ssh folder, see the documentation of prim-sync for more details
182
183
 
183
184
  options:
184
- -h, --help show this help message and exit
185
- -i {test,start,stop}, --intent {test,start,stop}
186
- what to do with the apps, default: test
185
+ -h, --help show this help message and exit
186
+ -i, --intent {test,start,stop} what to do with the apps, default: test
187
187
 
188
188
  logging:
189
- -t, --timestamp prefix each message with an UTC timestamp
190
- -s, --silent only errors printed
191
- --debug use debug level logging and add stack trace for exceptions, disables the --silent and enables the --timestamp options
189
+ -t, --timestamp prefix each message with an UTC timestamp
190
+ -s, --silent only errors printed
191
+ --debug use debug level logging and add stack trace for exceptions, disables the --silent and enables the --timestamp options
192
192
 
193
193
  VPN:
194
194
  To use --tailscale option you must install Tailscale and configure Tailscale VPN on your phone and your laptop
195
195
  To use --funnel option you must configure Tailscale Funnel on your laptop for prim-ctrl's local webhook to accept responses from the Automate app
196
196
  (eg.: tailscale funnel --bg --https=8443 --set-path=/prim-ctrl "http://127.0.0.1:12345")
197
- Note: --funnel, --backup-state and --restore-state options can be used only when --tailscale is used
197
+ Note: --funnel, --restart-vpn, --backup-state and --restore-state options can be used only when --tailscale is used
198
198
  Note: --backup-state is accurate only, when --funnel is used
199
199
  Note: --accept-cellular option can be used only when --funnel is used
200
200
 
201
- --tailscale tailnet remote-machine-name sftp-port
202
- tailnet: your Tailscale tailnet name (eg. tailxxxx.ts.net)
203
- remote-machine-name: your phone's name within your tailnet (just the name, without the tailnet)
204
- sftp-port: Primitive FTPd's sftp port
205
- --funnel local-machine-name local-port local-path external-port secretfile
206
- local-machine-name: your laptop's name within your tailnet (just the name, without the tailnet)
207
- local-port: 12345 - if you used the example tailscale funnel command above (the local webhook will be started on this port)
208
- local-path: /prim-ctrl - if you used the example tailscale funnel command above
209
- external-port: 8443 - if you used the example tailscale funnel command above
210
- secretfile: filename containing Tailscale's Client secret (not API access token, not Auth key) that located under your .secrets folder
211
- (generated on https://login.tailscale.com/admin/settings/oauth, with 'devices:core:read' scope,
212
- save only the Client secret in the file, the Client ID is part of it)
213
- -ac, --accept-cellular in case of start, if WiFi is not connected, don't return error, but start VPN up
214
- -b, --backup-state in case of start, backup current state to stdout as single string (in case of an error, it will try to restore the original state but will not write it to stdout)
215
- -r STATE, --restore-state STATE in case of stop, restore previous state from STATE (use -b to get a valid STATE string)
201
+ --tailscale tailnet secretfile remote-machine-name sftp-port
202
+ tailnet: your Tailscale tailnet name (eg. tailxxxx.ts.net)
203
+ secretfile: filename containing Tailscale's Client secret (not API access token, not Auth key) that located under your .secrets folder
204
+ (generated on https://login.tailscale.com/admin/settings/trust-credentials, with 'devices:core:read' scope,
205
+ save only the Client secret in the file, the Client ID is part of it)
206
+ remote-machine-name: your phone's name within your tailnet (just the name, without the tailnet)
207
+ sftp-port: Primitive FTPd's sftp port
208
+ --funnel local-machine-name local-port local-path external-port
209
+ local-machine-name: your laptop's name within your tailnet (just the name, without the tailnet)
210
+ local-port: 12345 - if you used the example tailscale funnel command above (the local webhook will be started on this port)
211
+ local-path: /prim-ctrl - if you used the example tailscale funnel command above
212
+ external-port: 8443 - if you used the example tailscale funnel command above
213
+ -rv, --restart-vpn DAYS in case of start, even if connected locally, but VPN is not used in the past DAYS, start VPN up
214
+ -ac, --accept-cellular in case of start, if WiFi is not connected, don't return error, but start VPN up
215
+ -b, --backup-state in case of start, backup current state to stdout as single string (in case of an error, it will try to restore the original state but will not write it to stdout)
216
+ -r, --restore-state STATE in case of stop, restore previous state from STATE (use -b to get a valid STATE string)
216
217
  ```
217
218
 
@@ -7,7 +7,7 @@ Though Primitive FTPd consumes minimal power when it is not used, remote start/s
7
7
 
8
8
  But in case of Tailscale, it is a real battery and mobile network data drain when not used, local and remote start/stop is de facto very useful.
9
9
 
10
- With the help of this script you can sync your phone with eg. your home NAS server whereever your phone is on a WiFi network - or even on cellular. Your phone doesn't have to be on the same LAN to make zeroconf working when you have alternative access through VPN.
10
+ With the help of this script you can sync your phone with eg. your home NAS server whereever your phone is on a WiFi network - or even on cellular. Your phone doesn't have to be on the same WiFi to make zeroconf working when you have alternative access through VPN. But VPN can help even if the phone is on the same WiFi as eg. your laptop, but due to networking restrictions they can't access each other directly (eg. hotel or airport WiFi).
11
11
 
12
12
  See my other project, https://github.com/lmagyar/prim-sync, for bidirectional and unidirectional sync over SFTP (multiplatform Python script optimized for the Primitive FTPd SFTP server).
13
13
 
@@ -117,28 +117,29 @@ But if the script runs scheduled, we can't be sure whether the phone is on WiFi,
117
117
  Notes:
118
118
  - Even when -b option is **not** used, the script will output 'connected=(local|remote)', what you can use to determine whether to use -a option for the prim-sync script
119
119
  - If local Tailscale VPN was disconnected for a longer period (several hours), the public DNS records for Funnel are removed by Tailscale, and after connecting local Tailscale VPN to the tailnet it can take up to 10 minutes for Funnel's public DNS records to show up for your tailnet domain. If the script connects local Tailscale VPN to the tailnet, then it regularly checks and waits up to 10 minutes for the public DNS records to get updated.
120
+ - If you want to interrupt the synchronization, press Ctrl-C once, and wait few seconds until the script properly removes temporary files, saves it's internal state and restores Primitive FTPd and VPN states.
120
121
 
121
122
  ### Some example
122
123
 
123
124
  <details><summary>Ubuntu</summary>
124
125
 
125
126
  ```
126
- prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 tailscale-secretfile -t -i start -b
127
- prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 tailscale-secretfile -t -i stop -r ${PREV_STATE}
127
+ prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net tailscale-secretfile your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 -t -i start -b
128
+ prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net tailscale-secretfile your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 -t -i stop -r ${PREV_STATE}
128
129
  ```
129
130
  </details>
130
131
  <details><summary>Windows</summary>
131
132
 
132
133
  ```
133
- prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 tailscale-secretfile -t -i start -b
134
- prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 tailscale-secretfile -t -i stop -r !PREV_STATE!
134
+ prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net tailscale-secretfile your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 -t -i start -b
135
+ prim-ctrl Automate youraccount@gmail.com "SOME MANUFACTURER XXXX" automate your-phone-pftpd id_ed25519_sftp --tailscale tailxxxx.ts.net tailscale-secretfile your-phone 2222 --funnel your-laptop 12345 /prim-ctrl 8443 -t -i stop -r !PREV_STATE!
135
136
  ```
136
137
  </details>
137
138
 
138
139
  ### Options
139
140
 
140
141
  ```
141
- usage: prim-ctrl Automate [-h] [-i {test,start,stop}] [-t] [-s] [--debug] [--tailscale tailnet remote-machine-name sftp-port] [--funnel local-machine-name local-port local-path external-port secretfile] [-ac] [-b] [-r STATE]
142
+ usage: prim-ctrl Automate [-h] [-i {test,start,stop}] [-t] [-s] [--debug] [--tailscale tailnet secretfile remote-machine-name sftp-port] [--funnel local-machine-name local-port local-path external-port] [-rv DAYS] [-ac] [-b] [-r STATE]
142
143
  automate-account automate-device automate-tokenfile server-name keyfile
143
144
 
144
145
  Remote control of your phone's Primitive FTPd and optionally Tailscale app statuses via the Automate app, for more details see https://github.com/lmagyar/prim-ctrl
@@ -150,46 +151,46 @@ Note: optionally if your laptop is accessible through Tailscale Funnel then VPN
150
151
  Output: even when -b option is not used, the script will output 'connected=(local|remote)', what you can use to determine whether to use -a option for the prim-sync script
151
152
 
152
153
  positional arguments:
153
- automate-account your Google account email you set up in the Automate flow's 2nd block's (Set variable google_account to...) Value field
154
- automate-device the device name you can see at the Automate flow's Cloud receive block's This device field
155
- automate-tokenfile filename containing Automates's Secret that located under your .secrets folder
156
- (generated on https://llamalab.com/automate/cloud, use the same Google account you set the automate_account option to)
157
- Note: if the account you use to send messages is different from the automate_account option,
158
- set it up in the Automate flow's 3rd block's (Set variable other_managing_accounts to...) Value field
159
- server-name the Servername configuration option from Primitive FTPd app
160
- keyfile private SSH key filename located under your .ssh folder, see the documentation of prim-sync for more details
154
+ automate-account your Google account email you set up in the Automate flow's 2nd block's (Set variable google_account to...) Value field
155
+ automate-device the device name you can see at the Automate flow's Cloud receive block's This device field
156
+ automate-tokenfile filename containing Automates's Secret that located under your .secrets folder
157
+ (generated on https://llamalab.com/automate/cloud, use the same Google account you set the automate_account option to)
158
+ Note: if the account you use to send messages is different from the automate_account option,
159
+ set it up in the Automate flow's 3rd block's (Set variable other_managing_accounts to...) Value field
160
+ server-name the Servername configuration option from Primitive FTPd app
161
+ keyfile private SSH key filename located under your .ssh folder, see the documentation of prim-sync for more details
161
162
 
162
163
  options:
163
- -h, --help show this help message and exit
164
- -i {test,start,stop}, --intent {test,start,stop}
165
- what to do with the apps, default: test
164
+ -h, --help show this help message and exit
165
+ -i, --intent {test,start,stop} what to do with the apps, default: test
166
166
 
167
167
  logging:
168
- -t, --timestamp prefix each message with an UTC timestamp
169
- -s, --silent only errors printed
170
- --debug use debug level logging and add stack trace for exceptions, disables the --silent and enables the --timestamp options
168
+ -t, --timestamp prefix each message with an UTC timestamp
169
+ -s, --silent only errors printed
170
+ --debug use debug level logging and add stack trace for exceptions, disables the --silent and enables the --timestamp options
171
171
 
172
172
  VPN:
173
173
  To use --tailscale option you must install Tailscale and configure Tailscale VPN on your phone and your laptop
174
174
  To use --funnel option you must configure Tailscale Funnel on your laptop for prim-ctrl's local webhook to accept responses from the Automate app
175
175
  (eg.: tailscale funnel --bg --https=8443 --set-path=/prim-ctrl "http://127.0.0.1:12345")
176
- Note: --funnel, --backup-state and --restore-state options can be used only when --tailscale is used
176
+ Note: --funnel, --restart-vpn, --backup-state and --restore-state options can be used only when --tailscale is used
177
177
  Note: --backup-state is accurate only, when --funnel is used
178
178
  Note: --accept-cellular option can be used only when --funnel is used
179
179
 
180
- --tailscale tailnet remote-machine-name sftp-port
181
- tailnet: your Tailscale tailnet name (eg. tailxxxx.ts.net)
182
- remote-machine-name: your phone's name within your tailnet (just the name, without the tailnet)
183
- sftp-port: Primitive FTPd's sftp port
184
- --funnel local-machine-name local-port local-path external-port secretfile
185
- local-machine-name: your laptop's name within your tailnet (just the name, without the tailnet)
186
- local-port: 12345 - if you used the example tailscale funnel command above (the local webhook will be started on this port)
187
- local-path: /prim-ctrl - if you used the example tailscale funnel command above
188
- external-port: 8443 - if you used the example tailscale funnel command above
189
- secretfile: filename containing Tailscale's Client secret (not API access token, not Auth key) that located under your .secrets folder
190
- (generated on https://login.tailscale.com/admin/settings/oauth, with 'devices:core:read' scope,
191
- save only the Client secret in the file, the Client ID is part of it)
192
- -ac, --accept-cellular in case of start, if WiFi is not connected, don't return error, but start VPN up
193
- -b, --backup-state in case of start, backup current state to stdout as single string (in case of an error, it will try to restore the original state but will not write it to stdout)
194
- -r STATE, --restore-state STATE in case of stop, restore previous state from STATE (use -b to get a valid STATE string)
180
+ --tailscale tailnet secretfile remote-machine-name sftp-port
181
+ tailnet: your Tailscale tailnet name (eg. tailxxxx.ts.net)
182
+ secretfile: filename containing Tailscale's Client secret (not API access token, not Auth key) that located under your .secrets folder
183
+ (generated on https://login.tailscale.com/admin/settings/trust-credentials, with 'devices:core:read' scope,
184
+ save only the Client secret in the file, the Client ID is part of it)
185
+ remote-machine-name: your phone's name within your tailnet (just the name, without the tailnet)
186
+ sftp-port: Primitive FTPd's sftp port
187
+ --funnel local-machine-name local-port local-path external-port
188
+ local-machine-name: your laptop's name within your tailnet (just the name, without the tailnet)
189
+ local-port: 12345 - if you used the example tailscale funnel command above (the local webhook will be started on this port)
190
+ local-path: /prim-ctrl - if you used the example tailscale funnel command above
191
+ external-port: 8443 - if you used the example tailscale funnel command above
192
+ -rv, --restart-vpn DAYS in case of start, even if connected locally, but VPN is not used in the past DAYS, start VPN up
193
+ -ac, --accept-cellular in case of start, if WiFi is not connected, don't return error, but start VPN up
194
+ -b, --backup-state in case of start, backup current state to stdout as single string (in case of an error, it will try to restore the original state but will not write it to stdout)
195
+ -r, --restore-state STATE in case of stop, restore previous state from STATE (use -b to get a valid STATE string)
195
196
  ```