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