Sync against taskchampion-sync-server (#3118)
This removes use of gnutls and the TLS implementation, which is no longer needed (task synchronization is handled via Taskchampion, which uses `reqwest`, which handles TLS via other Rust dependencies). This incidentally removes the following config options: * `debug.tls` * `taskd.ca` * `taskd.certificate` * `taskd.ciphers` * `taskd.credentials` * `taskd.key` * `taskd.server` * `taskd.trust`
This commit is contained in:
Dustin J. Mitchell
committed by
GitHub
GitHub
parent
771977aa69
commit
31105c2ba3
@@ -1,51 +1,118 @@
|
||||
.TH task-sync 5 2016-02-24 "${PACKAGE_STRING}" "User Manuals"
|
||||
|
||||
.SH NAME
|
||||
task-sync \- A discussion and tutorial for the various task(1) data
|
||||
synchronization capabilities.
|
||||
task-sync \- A discussion and tutorial for the various
|
||||
.BR task (1)
|
||||
data synchronization capabilities.
|
||||
|
||||
.SH INTRODUCTION
|
||||
Taskwarrior has several sync options, both external and built in. If you wish
|
||||
to sync your data, choose one method only; mixing methods is going to lead to
|
||||
problems. Each of the methods discussed have their own strengths.
|
||||
|
||||
.SH ALTERNATIVES
|
||||
There are three alternatives for syncing data, which are:
|
||||
|
||||
1) Version control systems, such as git, hg, svn
|
||||
Taskwarrior can synchronize your tasks to a server. This has a few benefits:
|
||||
.br
|
||||
2) File sharing systems, such as DropBox, Google Drive
|
||||
- Makes your tasks accessible from multiple systems, called "replicas".
|
||||
.br
|
||||
3) Using the Taskserver and the 'sync' command
|
||||
|
||||
|
||||
.SH OPTION 1: VERSION CONTROL SYSTEMS
|
||||
There are several good, distributed VCS systems (git, hg, ...) and centralized
|
||||
VCS systems (svn, cvs ...), and they all function in a similar fashion for our
|
||||
purposes.
|
||||
|
||||
Setup is straightforward. You place your .task directory under revision
|
||||
control. You then need to perform a regular commit/push/pull/update to make
|
||||
sure that the data is propagated when needed. You can even do this using shell
|
||||
scripts so that every task command is preceded by a 'pull' and followed by
|
||||
a 'push'.
|
||||
|
||||
Strengths:
|
||||
- Provides a backup of your tasks.
|
||||
.br
|
||||
- Good data transport mechanisms
|
||||
.br
|
||||
- Secure transport options
|
||||
- Saves disk space.
|
||||
|
||||
Weaknesses:
|
||||
.br
|
||||
- You need proficiency with VCS tools
|
||||
.br
|
||||
- You will need to manually resolve conflicts frequently
|
||||
.br
|
||||
- You need to provide the mechanism for making sure copies are up to date
|
||||
For example, you might want a replica of your tasks on your laptop and on your phone.
|
||||
|
||||
NOTE: A side-effect of synchronization is that once changes have been
|
||||
synchronized, they cannot be undone. This means that each time synchronization
|
||||
is run, it is no longer possible to undo previous operations.
|
||||
|
||||
.SH CONFIGURATION
|
||||
|
||||
To synchronize your tasks to a sync server, you will need the following
|
||||
information from the server administrator:
|
||||
|
||||
.br
|
||||
- The server's URL ("origin", such as "https://tw.example.com")
|
||||
.br
|
||||
- A client key ("client_key") identifying your tasks
|
||||
.br
|
||||
- An encryption secret ("encryption_secret") used to encrypt and decrypt your tasks. This can be any secret string, and must match for all replicas using the same client key.
|
||||
|
||||
Tools such as
|
||||
.BR pwgen (1)
|
||||
can generate suitable secret values.
|
||||
|
||||
Configure Taskwarrior with these details:
|
||||
|
||||
$ task config sync.server.origin <origin>
|
||||
$ task config sync.server.client_key <client_key>
|
||||
$ task config sync.server.encryption_secret <encryption_secret>
|
||||
|
||||
.SS Adding a Replica
|
||||
|
||||
To add a new replica, configure a new, empty replica identically to
|
||||
the existing replica, and run `task sync`.
|
||||
|
||||
.SS When to Synchronize
|
||||
|
||||
Taskwarrior can perform a sync operation at every garbage collection (gc) run.
|
||||
This is the default, and is appropriate for local synchronization.
|
||||
|
||||
For synchronization to a server, a better solution is to run
|
||||
|
||||
$ task sync
|
||||
|
||||
periodically, such as via
|
||||
.BR cron (8) .
|
||||
|
||||
.SS Local Synchronization
|
||||
|
||||
In order to take advantage of synchronization's side effect of saving disk
|
||||
space without setting up a remote server, it is possible to sync tasks locally.
|
||||
To configure local sync:
|
||||
|
||||
$ task config sync.local.server_dir /path/to/sync
|
||||
|
||||
The default configuration is to sync to a database in the task directory
|
||||
("data.location").
|
||||
|
||||
.SH RUNNING TASKCHAMPION-SYNC-SERVER
|
||||
|
||||
The Taskchampion sync server is an HTTP server supporting multiple users.
|
||||
Users are identified by a client key, and users with different client keys are
|
||||
entirely independent. Task data is encrypted by Taskwarrior, and the sync
|
||||
server never sees un-encrypted data.
|
||||
|
||||
To start the server, run it in your preferred HTTP hosting environment, using
|
||||
`--port` to set the TCP port on which it should listen. It is recommended to
|
||||
use TLS to protect communications with the server, but this is not required.
|
||||
|
||||
The server stores its data in a database, the path to which is given by the
|
||||
`--data-dir` argument, defaulting to "/var/lib/taskchampion-sync-server".
|
||||
|
||||
For example:
|
||||
|
||||
$ taskchampion-sync-server --port 8443 --data-dir /storage/taskdata
|
||||
|
||||
.SS Adding a New User
|
||||
|
||||
To add a new user to the server, invent a new client key with a tool like
|
||||
`uuidgen` or an online UUID generator. There is no need to configure the server
|
||||
for this new client key: the sync server will automatically create a new user
|
||||
whenever presented with a new client key. Supply the key, along with the
|
||||
origin, to the user for inclusion in their Taskwarrior config. The user should
|
||||
invent their own "encryption_secret".
|
||||
|
||||
.SH AVOIDING DUPLICATE RECURRING TASKS
|
||||
|
||||
If you run multiple clients that sync to the same server, you will need to run
|
||||
this command on your primary client (the one you use most often):
|
||||
|
||||
$ task config recurrence on
|
||||
|
||||
And on the other clients, run:
|
||||
|
||||
$ task config recurrence off
|
||||
|
||||
This protects you against the effects of a sync/duplication bug.
|
||||
|
||||
.SH ALTERNATIVE: FILE SHARING SERVICES
|
||||
|
||||
.SH OPTION 2: FILE SHARING SERVICES
|
||||
There are many file sharing services, such as DropBox, Amazon S3, Google Drive,
|
||||
SkyDrive and more. This technique involves storing your .task directory in a
|
||||
shared directory under the control of the file hosting services.
|
||||
@@ -74,78 +141,6 @@ Weaknesses:
|
||||
- Tasks are not properly merged
|
||||
|
||||
|
||||
.SH OPTION 3: TASKSERVER
|
||||
The Taskserver was designed for this purpose to be secure, fast and conflict-
|
||||
free, allowing data interchange between assorted Taskwarrior clients, and
|
||||
tolerant of network connectivity problems.
|
||||
|
||||
There is a 'sync' command built in to Taskwarrior (provided the GnuTLS library
|
||||
is installed), and with a server account and client configuration, syncing is
|
||||
done on demand.
|
||||
|
||||
Setup is a matter of creating an account on a Taskserver (see your Taskserver
|
||||
provider or operate your own - see
|
||||
https://taskwarrior.org/docs/taskserver/setup.html)
|
||||
|
||||
Once you have an account, you'll receive a certificate, key, and credentials.
|
||||
You'll need to put the certificate and key somewhere like this:
|
||||
|
||||
$ cp <name>.cert.pem ~/.task
|
||||
$ cp <name>.key.pem ~/.task
|
||||
|
||||
Then you configure Taskwarrior, using the provided details:
|
||||
|
||||
$ task config taskd.certificate ~/.task/<name>.cert.pem
|
||||
$ task config taskd.key ~/.task/<name>.key.pem
|
||||
$ task config taskd.credentials <organization>/<name>/<UUID>
|
||||
$ task config taskd.server <server domain>:<port>
|
||||
|
||||
If you are using a private server, you are likely also using a self-signed
|
||||
certificate, which means you will need one of the following additional entries:
|
||||
|
||||
$ task config taskd.ca ~/.task/ca.cert.pem
|
||||
|
||||
The CA (Certificate Authority) will be used to verify the server certificate.
|
||||
|
||||
After setup, you run a one-time sync initialization, like this:
|
||||
|
||||
$ task sync init
|
||||
|
||||
This will make sure your client and the server are properly in sync to begin
|
||||
with. From this point on, you never run the 'initialize' command again, just
|
||||
go about your business, and when you want to sync, run this:
|
||||
|
||||
$ task sync
|
||||
|
||||
You'll see a summary of how many tasks were uploaded and downloaded. You can
|
||||
safely run the command as often as you like. When there are no changes to sync,
|
||||
nothing happens. If you do not have connectivity, your task changes accumulate
|
||||
so that when you next run 'sync' with proper connectivity, the changes are
|
||||
properly handled, in the right order.
|
||||
|
||||
If you run multiple clients that sync to the same server, you will need to run
|
||||
this command on your primary client (the one you use most often):
|
||||
|
||||
$ task config recurrence on
|
||||
|
||||
And on the other clients, run:
|
||||
|
||||
$ task config recurrence off
|
||||
|
||||
This protects you against the effects of a sync/duplication bug.
|
||||
|
||||
Strengths:
|
||||
.br
|
||||
- Secure communication
|
||||
.br
|
||||
- Minimal bandwidth
|
||||
.br
|
||||
- Tolerates connectivity outage
|
||||
|
||||
Weaknesses:
|
||||
.br
|
||||
- You need to manage your own server, or gain access to a hosted server.
|
||||
|
||||
.SH "CREDITS & COPYRIGHTS"
|
||||
Copyright (C) 2006 \- 2021 T. Babej, P. Beckingham, F. Hernandez.
|
||||
|
||||
|
||||
@@ -538,13 +538,9 @@ Shows statistics of the tasks defined by the filter. Is affected by the context.
|
||||
Shows a report of aggregated task status by project. Is affected by the context.
|
||||
|
||||
.TP
|
||||
.B task sync [init]
|
||||
.B task sync
|
||||
The sync command synchronizes data with the Taskserver, if configured.
|
||||
|
||||
The init subcommand should only ever be run once, and only on one client, because
|
||||
it sends all data to the Taskserver. This allows all the subsequent sync commands
|
||||
to only send small deltas.
|
||||
|
||||
Note: If you use multiple sync clients, make sure this setting (which is the default)
|
||||
is on your primary client:
|
||||
|
||||
|
||||
@@ -516,7 +516,7 @@ debug output can be useful. It can also help explain how the command line is
|
||||
being parsed, but the information is displayed in a developer-friendly, not a
|
||||
user-friendly way.
|
||||
|
||||
Turning debug on automatically sets debug.hooks=1, debug.parser=1 and debug.tls=2
|
||||
Turning debug on automatically sets debug.hooks=1 and debug.parser=1
|
||||
if they do not already have assigned values. Defaults to "0".
|
||||
|
||||
.TP
|
||||
@@ -531,11 +531,6 @@ Level 1 shows the final parse tree.
|
||||
Level 2 shows the parse tree from all phases of the parse.
|
||||
Level 3 shows expression evaluation details.
|
||||
|
||||
.TP
|
||||
.B debug.tls=0
|
||||
Controls the GnuTLS diagnostic level. For 'sync' debugging. Level 0 means no
|
||||
diagnostics. Level 9 is the highest. Level 2 is a good setting for debugging.
|
||||
|
||||
.TP
|
||||
.B obfuscate=0
|
||||
When set to '1', will replace all report text with 'xxx'.
|
||||
@@ -1527,58 +1522,6 @@ context.home.rc.default.command=home_report
|
||||
These configuration settings are used to connect and sync tasks with the task
|
||||
server.
|
||||
|
||||
.TP
|
||||
.B taskd.server=<host>:<port>
|
||||
.RS
|
||||
Specifies the hostname and port of the Taskserver. Hostname may be an IPv4 or
|
||||
IPv6 address, or domain. Port is an integer.
|
||||
.RE
|
||||
|
||||
.TP
|
||||
.B taskd.credentials=<organization>/<user>/<key>
|
||||
.RS
|
||||
User identification for the Taskserver, which includes a private key.
|
||||
.RE
|
||||
|
||||
.TP
|
||||
.B taskd.certificate=<path>
|
||||
.RS
|
||||
Specifies the path to the client certificate used for identification with the
|
||||
Taskserver.
|
||||
.RE
|
||||
|
||||
.TP
|
||||
.B taskd.key=<path>
|
||||
.RS
|
||||
Specifies the path to the client key used for encrypted communication with the
|
||||
Taskserver.
|
||||
.RE
|
||||
|
||||
.TP
|
||||
.B taskd.ca=<path>
|
||||
.RS
|
||||
Specifies the path to the CA certificate in the event that your Taskserver is
|
||||
using a self-signed certificate. Optional.
|
||||
.RE
|
||||
|
||||
.TP
|
||||
.B taskd.trust=strict|ignore hostname|allow all
|
||||
.RS
|
||||
This settings allows you to override the trust level when server certificates
|
||||
are validated. With "allow all", the server certificate is trusted
|
||||
automatically. With "ignore hostname", the server certificate is verified but
|
||||
the hostname is ignored. With "strict", the server certificate is verified.
|
||||
Default is "strict", which requires full validation.
|
||||
.RE
|
||||
|
||||
.TP
|
||||
.B taskd.ciphers=NORMAL
|
||||
Override of the cipher selection. The set of ciphers used by TLS may be
|
||||
controlled by both server and client. There must be some overlap between
|
||||
client and server supported ciphers, or communication cannot occur.
|
||||
Default is "NORMAL". See GnuTLS documentation for full details.
|
||||
.RE
|
||||
|
||||
.SH "CREDITS & COPYRIGHTS"
|
||||
Copyright (C) 2006 \- 2021 T. Babej, P. Beckingham, F. Hernandez.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user