diff --git a/README.md b/README.md index 856f697..9870470 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ Remove all query parameters by passing in an empty string. ``` import querymodifier; set req.url = querymodifier.modifyparams(url=req.url, params="", exclude_params=true); -# Or use the conveniecen function, `excludeallparams`. +# Or use the convenience function, `excludeallparams`. # set req.url = querymodifier.excludeallparams(url=req.url); # Original URL: example.com/?search=name&ts=123456789&v=123456789&id=987654321 @@ -80,6 +80,8 @@ I'm happy to review any PRs. Any bug reports are also welcome. ### Debugging +#### ASan + The module can also be built with [`AddressSanitizer`](https://github.com/google/sanitizers/wiki/AddressSanitizer) support. It is recommended that when developing on the module, you build with `AddressSanitizer` support enabled in order to help identify any memory issues with the VMOD. @@ -94,9 +96,47 @@ There are also some scripts in the `debug` directory to assist. Navigate to the _Note_: Do not use the module built with ASan support in production. This is meant for development purposes only. +#### gdb + +`gdb` is also included in the debug Dockerfile for your convenience. + +- After you've brought up Docker Compose, exec into the Varnish container. + +```bash +docker compose exec varnish +``` + +- Attach `gdb` to the Varnish child process. You can either get the PID with `ps` or Varnish will print the child PID to the console like `varnish-1 | Debug: Child (31) Started`. + +```bash +(gdb) attach 31 +``` + +- Set a breakpoint, for example on the `vmod_modifyparams` function. A `.gdbinit` file is included in the Docker container to instruct `gdb` where to find the VMOD shared libraries. + +```bash +(gdb) b vmod_modifyparams +Breakpoint 1 at 0xffff7e0b14cc: file vmod_querymodifier.c, line 219. +``` + +- Send a request to `http://localhost:8080` that exercises the VMOD. + +- Continue the debugger and then use `gdb` as you normally would. + +```bash +(gdb) c +Continuing. +[Switching to Thread 0xffff855cf140 (LWP 372)] + +Thread 101 "cache-worker" hit Breakpoint 1, vmod_modifyparams (ctx=0xffff855cd9b8, uri=0xffff79a3d8ac "/?blah=1&ts=1", params_in=0xffff7e0e7610 "ts,v,cacheFix,date", + exclude_params=1) at vmod_querymodifier.c:219 +219 CHECK_OBJ_NOTNULL(ctx, VRT_CTX_MAGIC); +``` + ## Acknowledgements - The NY Times [`libvmod-queryfilter` VMOD](https://github.com/nytimes/libvmod-queryfilter/) for insipiration. +- dridi [`vmod-querystring` VMOD](https://git.sr.ht/~dridi/vmod-querystring) for insipiration. - [`vcdk`](https://github.com/nigoroll/vcdk/) for the project structure. - Guillaume Quintard for the [VMOD tutorial](https://info.varnish-software.com/blog/creating-a-vmod-vmod-str). diff --git a/debug/.gdbinit b/debug/.gdbinit new file mode 100644 index 0000000..336b4fc --- /dev/null +++ b/debug/.gdbinit @@ -0,0 +1 @@ +set solib-search-path /var/lib/varnish/varnishd/vmod_cache diff --git a/debug/Dockerfile b/debug/Dockerfile index 711fc88..ca02b05 100644 --- a/debug/Dockerfile +++ b/debug/Dockerfile @@ -9,12 +9,14 @@ RUN apt-get update && \ automake \ python3-docutils \ autoconf-archive \ - libasan8 + libasan8 \ + gdb \ + procps WORKDIR / COPY . /libvmod-querymodifier RUN cd /libvmod-querymodifier \ - && ./bootstrap --enable-asan \ + && ./bootstrap --enable-asan CFLAGS="-g -O0" \ && make \ && make install diff --git a/debug/docker-compose.yml b/debug/docker-compose.yml index c036857..5646aaa 100644 --- a/debug/docker-compose.yml +++ b/debug/docker-compose.yml @@ -11,6 +11,11 @@ services: volumes: - ./default.vcl:/etc/varnish/default.vcl - ./entrypoint.sh:/entrypoint.sh + - ./.gdbinit:/root/.gdbinit + cap_add: + - SYS_PTRACE + security_opt: + - seccomp=unconfined nginx: image: nginx:1.27-alpine ports: