c/ooni-probe-cli
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
317 Commits 6 Branches 0 Tags 8.8 MiB
Go 97.6%
Python 1.2%
Shell 0.9%
Makefile 0.3%
040bee0ee6
Go to file
Simone Basso 040bee0ee6
Optionally treat EOF on stdin just like SIGTERM (#111) 
* Optionally treat EOF on stdin just like SIGTERM

On Unix, Node.js allows us to gracefully kill a process. On Windows
this is more compex. You certainly cannot rely on the default `kill()`
function, which calls `TerminateProcess`.

There is a bunch of C/C++ extensions that in principle allow you to
attempt to gracefully shutdown a Windows process.

But, hey, here's a reality check. Node.js controls our stdin. Node.js
does IPC easy. Controlling uv_spawn flags and using the right not well maintained
C/C++ Node.js extension to kill a process is fragile.

So, treat EOF and any other error on stdin as equivalent to SIGTERM.

However, systemd.

The sane thing to do with systemd is `StandardInput=null`. With such
configuration, stdin immediately returns EOF.

Then, introduce the `OONI_STDIN_EOF_IMPLIES_SIGTERM` environment
variable. When it is `true`, this behaviour is enabled, e.g.:

```bash
export OONI_STDIN_EOF_IMPLIES_SIGTERM=true  # behaviour enabled
ooniprobe run
```

I want the default to be disabled because:

1. in the future we may find a better way to solve this problem and I
don't want the _default behaviour_ to change in such case

2. we know we need this knob for ooniprobe-desktop, and we will not
fail to provide it, so it won't suprise/damage us

3. a person trying to write a systemd unit for ooniprobe would be very
surprised to find out they need to disable this behaviour, if it was
enabled by default by this PR

Hence, I believe this design is consistent with designing for the
future and for trying to minimize surprises.

Also, why an environment variable and not a command line flag? Because:

1. we don't want such hypothetical flag to be available where it does not
make sense, e.g., for all subcommands but `run`

2. we don't want the ooni/probe-desktop app to write conditional
code because it needs to check the command we're using and then decide
whether to add such hypothetical flag

Also, why not enabling this only on Windows? Because again we don't
want the ooni/probe-desktop app to write conditional code.

To summarize: we want ooni/probe-desktop app to see the same behaviour
everywhere and we want others to be the least surprised.

Related to https://github.com/ooni/probe/issues/1005

* Update ooni.go
2020-02-13 14:53:06 +01:00
cmd/ooniprobe Rename the binary as ooniprobe (#58) 2019-10-02 19:27:15 +02:00
config Merge pull request #110 from ooni/no-help 2020-02-13 14:21:37 +01:00
data Remove help link from the default config 2020-02-12 15:09:59 +01:00
docs Address feedback from @bassosimone 2019-12-04 13:13:13 +02:00
internal Optionally treat EOF on stdin just like SIGTERM (#111) 2020-02-13 14:53:06 +01:00
nettests Merge pull request #108 from ooni/issue/316 2020-02-13 14:22:59 +01:00
scripts Move launchd script into the Readme 2020-01-29 09:43:39 +01:00
testdata Remove help link from the default config 2020-02-12 15:09:59 +01:00
utils Use ~/.ooniprobe as the home directory (#101) 2020-01-27 15:19:32 +01:00
version Bump version number 2020-02-05 18:38:23 +01:00
.dockerignore travis: run goveralls inside the docker container 2019-12-26 19:13:25 +00:00
.gitignore Add build artifacts to .gitignore 2020-02-10 10:43:13 +01:00
.travis.yml travis: run goveralls inside the docker container 2019-12-26 19:13:25 +00:00
build.sh bash on bash 2020-01-30 11:38:30 +01:00
Dockerfile travis: run goveralls inside the docker container 2019-12-26 19:13:25 +00:00
go.mod go.mod go.sum: update all dependencies (#107) 2020-02-11 09:21:56 +01:00
go.sum go.mod go.sum: update all dependencies (#107) 2020-02-11 09:21:56 +01:00
LICENSE.md Add LICENSE.md 2018-07-11 18:06:27 +02:00
ooni_test.go Allow to specify custom software name and version (#94) 2019-12-29 14:07:57 +01:00
ooni.go Optionally treat EOF on stdin just like SIGTERM (#111) 2020-02-13 14:53:06 +01:00
Readme.md Add launchctl command to Readme 2020-01-29 09:45:51 +01:00

Readme.md

OONI Probe CLI

The next generation OONI Probe Command Line Interface.

User setup

  1. Go into the releases and download the release for your architecture and platform

  2. Extract the tarball with tar xvzf ooniprobe_*.tar.gz

  3. Copy the ooniprobe binary into a location in your $PATH, for example /usr/local/bin/ooniprobe

  4. Run ooniprobe run to perform all the tests

Optional:

Add a crontab entry (on linux) to run ooniprobe daily at a random time:

(crontab -l 2>/dev/null; echo "$(( ( RANDOM % 60 )  + 1 )) $(( ( RANDOM % 24 )  + 1 )) * * * ooniprobe run") | crontab -

On macOS you can configure OONI Probe to run automatically using launchd.

Below is a sample launchd script, that should be placed inside of ~/Library/LaunchAgents/org.ooni.probe.cli.plist.

Be sure to replace /PATH/TO/BINARY/ooniprobe with the actual install location of the ooniprobe binary and /PATH/TO/CONFIG/config-100sites.json with the location of a file which limits the testing to 100 URLs.

You may also want to adjust the locations of the logs.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>org.ooni.probe.daily-run</string>

    <key>KeepAlive</key>
    <false/>
    <key>RunAtLoad</key>
    <true/>

    <key>Program</key>
    <string>/PATH/TO/BINARY/ooniprobe</string>
    <key>ProgramArguments</key>
    <array>
        <string>--config="/PATH/TO/CONFIG/config-100sites.json"</string>
        <string>--batch</string>
        <string>run</string>
    </array>

    <key>StartInterval</key>
    <integer>3600</integer>

    <key>StandardErrorPath</key>
    <string>/tmp/ooniprobe-cli.err</string>

    <key>StandardOutPath</key>
    <string>/tmp/ooniprobe-cli.out</string>
</dict>
</plist>

Once you have written the file, you can enable to run automatically by doing: launchctl load org.ooni.probe.cli.plist.

Development setup

Be sure you have golang >= 1.13. We use golang modules. Run

./build.sh help

to get information on the supported systems as well as to get instructions on how to install dependencies.

Updating dependencies

  1. update every direct dependency in go.mod except probe-engine using go get -u -v $dependency

  2. pin to the latest version of the probe-engine with go get -v github.com/ooni/probe-engine@tag

  3. remove all indirect dependencies from go.mod and merge the content of probe-engine's go.mod into our go.mod

  4. go mod tidy

The rationale of this procedure is that we want to pin exactly to a specific version of psiphon and of its dependencies.

Releasing

./build.sh release

and follow instructions.