Project

General

Profile

User manual » History » Version 1

koszko, 10/12/2022 08:05 PM
write some basic documentation for the Haketilo proxy usage

1 1 koszko
# User manual
2
This page documents the usage of Haketilo proxy. For a documentation of Haketilo extension's usage (in maintenance mode), see [[User manual (browser extension)|here]].
3
4
{{toc}}
5
6
## Installation
7
8
The recommended way of installing Haketilo is by using the "relocatable standalone binary release for x86-64 computers" from the [[Releases]] page. The release tarball is prepared using [GNU Guix](https://guix.gnu.org/) package manager as described in Haketilo's [README.md](/projects/haketilo/repository/haketilo-and-hydrilla/revisions/master/entry/README.md) file. It can be used on top of most GNU/Linux systems, even those that don't have GNU Guix installed.
9
10
Once the `.tar.gz` release archive finishes downloading, create a new directory and extract the tarball there. You'll see a few executables named `haketilo`, `hydrilla-builder`, etc. They are ready to use. The release is *relocatable*, so it is also possible to move the executables to another place in the filesystem (together with the `gnu/` directory that was extracted with them) and run the programs from there.
11
12
## Running
13
14
You can start the proxy by running the executable named `haketilo`. Upon the first run, it will create a `.haketilo/` directory inside your user home directory. It will store its data (user scripts, cryptographic certificates, etc.) there.
15
16
If you're familiar with the command line, you can optionally tell Haketilo to listen on a different port number than the default of 8080 (`--port` option) or to use a different data directory than the default of `~/.haketilo` (`--directory` option).
17
18
## Configuring the browser
19
20
Once Haketilo is running, your web browser needs to be told to connect to the internet through it. You'll want to configure it to use the proxy at address 127.0.0.1 and port 8080 for both HTTP and HTTPs connections.
21
22
Under Firefox and derived browsers, the relevant settings can be accessed by navigating to `about:preferences`, scrolling all the way down to "Network Settings" and clicking on the "Settings…" button. You'll want to choose the "Manual proxy configuration" option, enter address and port in the fields next to the "HTTP proxy" label and tick the "Also use this proxy for HTTPS" checkbox beneath.
23
24
If you performed all the steps correctly, you can now access the locally-served configuration page of Haketilo at http://hkt.mitm.it. The browser does not yet know the security certificate of our proxy, so it might present to you a warning about the HTTPs version of the page being unavailable. In *this particular case* the warning is safe to ignore.
25
26
At this point the browser does not yet allow Haketilo to modify HTTP​**s** pages. For that, you need to visit http://mitm.it which is yet another page hosted locally by Haketilo. Once there, follow the instructions to install the certificate in your operating system, your browser or both.
27
28
All HTTP and most HTTPs websites should now load correctly in the browser. However, some user agents pin the certificates of certain sites. E.g. Mozilla Firefox by default pins the certificate used by https://mozilla.org. This security feature makes it impossible to access the site through Haketilo proxy. If you want to do that nevertheless, you might consider disabling the feature. For example, in Firefox-derived browsers this can be done by visiting the `about:config` page, looking up the `security.cert_pinning.enforcement_level` preference and setting its value to **0**.
29
30
## Managing the proxy
31
32
Haketilo can be configured from its locally-hosted meta-site https://hkt.mitm.it. Take a while to experiment a bit with the interface so that you can make yourself familiar it.
33
34
## Understanding the concepts
35
36
### Script blocking and injection
37
Haketilo combines features of a user script manager and a content blocker. Out of the box, it can be used to block site's JavaScript, similarly to how NoScript (for example) does it. Once you import custom scripts into Haketilo (either from a Hydrilla repository server or by typing code in a form on the import page), it can also inject them into pages.
38
39
Script blocking and injection is configured using [[URL patterns]]. Patterns have different specificity. More specific patterns will override the settings of the less specific ones. In short, for every visited page, Haketilo performs the following steps:
40
1. Try to find a script blocking/allowing/injection rule with a pattern matching page's URL. If found, apply the rule and don't perform the next step.
41
   * If multiple rules match, pick the one with the most specific pattern.
42
2. If no rules matched, check whether the default policy is to block scripts or allow them. Act accordingly.
43
44
In the end, Haketilo's action shall be one of the following:
45
* block page's own scripts
46
* allow page's own scripts to execute (i.e. don't do anything)
47
* inject the supplied user script **and** block page's own scripts
48
49
We can see that Haketilo's concepts are different from those of most user script managers. GreaseMonkey, for instance, executes user scripts alongside page's original scripts. Haketilo instead **replaces** page's scripts with the user-supplied ones.
50
51
### Packages and Libraries
52
53
To make mapping custom JavaScript applications and their dependencies to web pages more manageable, we introduced our own concept of packages. Currently, Haketilo understands 2 different types of items
54
* library - Also referred to as *resource*. Defines a set of scripts that can be injected together into a page. It can also name other libraries as its dependencies. When injecting scripts of a given library into some page, Haketilo will first inject scripts of all libraries depended on. Installed libraries are only viewable in Haketilo UI if advanced interface features are enabled.
55
* package - It associates URL patterns with libraries in a 1:1 fashion. If pattern `https://example.com/***` is associated with library `my-sample-lib` it means the scripts from `my-sample-res` should be injected into all HTTPs pages under the example.com domain.
56
57
For simple cases, this may be overly complex. Because of that, Haketilo's interface contains a simple form that can be used to quickly define a script payload for a set of URL patterns.
58
59
Packages and libraries can also be installed from Hydrilla repository which serves both simple and complex (i.e. multi-library) payloads. Defining more complex packages and libraries within Haketilo itself is not yet supported.
60
61
## What to do next
62
63
Please [[Reporting bugs|REPORT BUGS]]. This is incredibly important. If nobody reports them, they likely won't get fixed.
64
65
You might want to learn about [[Known limitations|current limitations]] of Haketilo. If despite these you like the tool, please spread the word. We'll be also happy to receive some feedback or - if you're a programmer - code contributions. Consider [creating an account](/account/register) on our issue tracker or writing to koszko@koszko.org :)