From 34c43489f8d7e65dceb5c7b4ede5cf0434c085cb Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 18 Feb 2019 14:40:14 -0800 Subject: [PATCH] web: document --capabilities/--capabilities-header, editing [ci skip] --- hledger-web/Hledger/Web/WebOptions.hs | 8 +-- hledger-web/hledger-web.m4.md | 81 +++++++++++++++++++-------- 2 files changed, 61 insertions(+), 28 deletions(-) diff --git a/hledger-web/Hledger/Web/WebOptions.hs b/hledger-web/Hledger/Web/WebOptions.hs index a24f07ae4..d6f6411a6 100644 --- a/hledger-web/Hledger/Web/WebOptions.hs +++ b/hledger-web/Hledger/Web/WebOptions.hs @@ -54,13 +54,13 @@ webflags = , flagReq ["capabilities"] (\s opts -> Right $ setopt "capabilities" s opts) - "CAP,CAP2" - "enable these capabilities - comma-separated, possible values are: view, add, manage (default: view,add)" + "CAP[,CAP..]" + "enable the view, add, and/or manage capabilities (default: view,add)" , flagReq ["capabilities-header"] (\s opts -> Right $ setopt "capabilities-header" s opts) - "HEADER" - "read enabled capabilities from a HTTP header (e.g. X-Sandstorm-Permissions, disabled by default)" + "HTTPHEADER" + "read capabilities to enable from a HTTP header, like X-Sandstorm-Permissions (default: disabled)" ] webmode :: Mode [(String, String)] diff --git a/hledger-web/hledger-web.m4.md b/hledger-web/hledger-web.m4.md index e61a2978c..fa5ed8218 100644 --- a/hledger-web/hledger-web.m4.md +++ b/hledger-web/hledger-web.m4.md @@ -74,36 +74,63 @@ The default is `http://HOST:PORT/` using the server's configured host address an With `--file-url` you can set a different base url for static files, eg for better caching or cookie-less serving on high performance websites. -Note there is no built-in access control (aside from listening on 127.0.0.1 by default). -So you will need to hide hledger-web behind an authenticating proxy (such as apache or nginx) -if you want to restrict who can see and add entries to your journal. +# PERMISSIONS -Command-line options and arguments may be used to set an initial -filter on the data. This is not shown in the web UI, but it will be -applied in addition to any search query entered there. +By default, hledger-web allows anyone who can reach it to view the journal +and to add new transactions, but not to change existing data. -With journal and timeclock files (but not CSV files, currently) the -web app detects changes made by other means and will show the new data -on the next request. If a change makes the file unparseable, -hledger-web will show an error until the file has been fixed. +You can restrict who can reach it by - +- setting the IP address it listens on (see `--host` above). + By default it listens on 127.0.0.1, accessible to all users on the local machine. +- putting it behind an authenticating proxy, using eg apache or nginx +- custom firewall rules + +You can restrict what the users who reach it can do, by + +- using the `--capabilities=CAP[,CAP..]` flag when you start it, + enabling one or more of the following capabilities. The default value is `view,add`: + - `view` - allows viewing the journal file and all included files + - `add` - allows adding new transactions to the main journal file + - `manage` - allows editing, uploading or downloading the main or included files + +- using the `--capabilities-header=HTTPHEADER` flag to specify a HTTP header + from which it will read capabilities to enable. hledger-web on Sandstorm + uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions. + This is disabled by default. + +# EDITING + +Note that if you enable the `manage` capability mentioned above, +hledger-web lets you alter or erase (by editing or uploading) the journal +file and any files it includes. This is unlike any other hledger command. + +Normally whenever a file is changed in this way, hledger-web saves a numbered backup +(assuming file permissions allow it, the disk is not full, etc.) +It is not currently aware of version control systems; if you use one, +you'll have to arrange to commit the changes yourself (eg with a cron job +or a file watcher like entr). + +Also normally, edits which would leave the journal file(s) unparseable +or non-valid (eg with failing balance assertions) are prevented +(this needs re-testing). + +# RELOADING + +hledger-web detects changes made to the files by other means (eg if you edit +it directly, outside of hledger-web), and it will show the new data +when you reload the page or navigate to a new page. +If a change makes a file unparseable, +hledger-web will display an error message until the file has been fixed. # OPTIONS -Note: if invoking hledger-web as a hledger subcommand, write `--` before options as shown above. +Command-line options and arguments may be used to set an initial +filter on the data. These filter options are not shown in the web UI, +but it will be applied in addition to any search query entered there. + +Note: if invoking hledger-web as a hledger subcommand, write `--` before options, +as shown in the synopsis above. `--serve` : serve and log requests, don't browse or auto-exit @@ -123,6 +150,12 @@ You would change this when sharing over the network, or integrating within a lar hledger-web normally serves static files itself, but if you wanted to serve them from another server for efficiency, you would set the url with this. +`--capabilities=CAP[,CAP..]` +: enable the view, add, and/or manage capabilities (default: view,add) + +`--capabilities-header=HTTPHEADER` +: read capabilities to enable from a HTTP header, like X-Sandstorm-Permissions (default: disabled) + hledger input options: _inputoptions_