1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
# ISystemtap
Welcome to ISystemtap, to get started check the [usage](#usage) below and tryout the ISystemtap.ipynb
## Usage
### Local usage
Once ISystemtap is installed just run `jupyter-lab [notebook_name.ipynb]` and then select a new or existing ISystemtap notebook. For installation see [below](#local-installation)
### Container usage
No local installation of ISystemtap is needed. Once systemtap is installed the following can be run.
It is suggested to pull the pre-built image from `quay.io`, but it can optionally be locally built as well
```bash
stap-jupyter-container [--repo REPOSITORY] [--image IMAGE] [--tag TAG] [--keyname KEYNAME] --{run, pull, build, publish, remove}
```
* --keyname: The name of the key to use for ssh'ing from the container to the host to run the stap commands. There should exist both "keyname" and "keyname.pub" files
* --run: Runs the image (if not pulled / built locally pull it from `quay.io`)
* --pull: Pull the built image (Published to `quay.io/systemtap/isystemtap`)
* --build: Do a local container build
* --publish [For maintainers only]: Publish the image to the public repo
* --remove: Remove the local copy of the image
#### TL;DR
To get started just run `stap-jupyter-container --run`
#### Running as a superuser
Running the container as a superuser means that stap scripts will be run as root. Therefore there are 2 prerequisites
* Make sure to add `PermitRootLogin without-password` to `/etc/ssh/sshd_config`. Note this does not mean there is no authentication it means that logging in is only possible using a fallback method (in this case a public key authentication).
* Make sure that systemtap is installed by root
## Local Installation
Run `stap-jupyter-install`. This will install the ISystemtap kernel, syntax highlighting and language-server dependencies in `~/.systemtap/jupyter` (and the jupyter config directories). To uninstall add the `--remove` flag.
## Development Directory Structure
```
interactive-notebook
├── codemirror // Jupyterlab extension for syntax highlighting
│ ├── jupyterlab-stap-highlighting
│ │ └── ...
│ ├── lib
│ │ └── ...
│ └── package.json
│
├── container // Container which wraps up the pythonic install elements
│ ├── Dockerfile
│ └── runtime_container_config.sh
│
├── setup.py // setup for module. Included in stap-jupyter-install
├── isystemtap // the jupyter kernel source and config file
│ ├── *.py
│ └── kernel.json
│
├── tests // Some automated and manual tests (Note: to test the dir must be writable)
│ └── ...
│
├── ISystemtap.ipynb // An introductory notebook example
│
├── stap-jupyter-install.in // Used to generate the local install script
│
├── stap-jupyter-container.in // Used to generated container management script
│
├── jupyter_stap_lsp.json // The language server config file
│
└── requirements.txt // Python reqs
```
## FAQ
1. What if something goes wrong, and a systemtap kernel module is left running after ISystemtap shuts down
* All you need to do is kill the process and run `sudo staprun -d MODULE_NAME` (this can be checked in `/proc/systemtap`)
2. How do I build from source?
* The same as normal. `make; make install` followed by one of the above `stap-jupyter-*` commands
3. What does Error: OCI runtime error: crun: error creating systemd unit `libpod-*.scope: got failed` mean
* Some file systems have issues with `podman`, try running as a superuser
4. **I'm a maintainer who wants to publish the latest image**; how do I do this?
* After building and installing systemtap run `stap-jupyter-container --build && stap-jupyter-container --publish`
* After the build you will be prompted for a `quay.io` login. This will be followed by the image being published to `quay.io/systemtap/isystemtap`
|
