Debugging OSS Teleport with Dlv and VSCode

[stevenGravy]

If you're experiencing an issue or just curious here are steps to setup debugging with Teleport OSS. The examples here were done in a Ubuntu 20.04.2.0 desktop env on Teleport V6 alpha-2. This example shows running with sudo. You can certainly run without sudo if you choose not to do a ssh_service and use folders your user owns.

Ex Debugging:

Prerequisites:

• Install Go 1.15+ (https://golang.org/dl/go1.15.linux-amd64.tar.gz)
• Install VSCode
  • with Go 0.22.1 extension
• Install make
• Install dlv (https://github.com/go-delve/delve/blob/master/Documentation/installation/linux/install.md)
• sudo rights on the machine

1. Clone the current master

git clone https://github.com/gravitational/teleport.git

If you are investigating an issue on a particular version pull that branch.

2. Confirm Teleport build

make full
should produce Teleport executes in build folder with tctl, teleport, and tsh.

3. Configure Teleport.yaml

If you don't already have a teleport instance here is a sample configuration to start with.
/etc/teleport.yaml

teleport:
  nodename: developer
  data_dir: /var/lib/teleport
  auth_token: 8514c6371916636dc66afc94218b91af781093f5fb123dcf
  auth_servers:
  - 127.0.0.1:3025
  log:
    output: stderr
    severity: INFO
auth_service:
  enabled: "yes"
  listen_addr: 0.0.0.0:3025
  tokens:
  - proxy,node:8514c6371916636dc66afc94218b91af781093f5fb123dcf
ssh_service:
  enabled: "yes"
  labels:
    env: staging
  commands:
  - name: hostname
    command: [hostname]
    period: 1m0s
  - name: arch
    command: [uname, -p]
    period: 1h0m0s
proxy_service:
  enabled: "yes"

4. Build with Debug enabled

$ BUILDFLAGS="-gcflags 'all=-N -l'" make full
---> Building OSS binaries.
make build/teleport build/tctl build/tsh
make[1]: Entering directory '/home/developer/teleport'
GOOS=linux GOARCH=amd64 CGO_ENABLED=1 go build -tags "  " -o build/teleport -gcflags 'all=-N -l' ./tool/teleport
GOOS=linux GOARCH=amd64 CGO_ENABLED=1 go build -tags "  " -o build/tctl -gcflags 'all=-N -l' ./tool/tctl
GOOS=linux GOARCH=amd64 CGO_ENABLED=1 go build -tags " " -o build/tsh -gcflags 'all=-N -l' ./tool/tsh
make[1]: Leaving directory '/home/developer/teleport'
---> Attaching OSS web assets.
cat build/webassets.zip >> build/teleport
rm -fr build/webassets.zip
zip -q -A build/teleport

5. Open VSCode

Add a attach option

{
    "version": "0.2.0",
    "configurations": [
   {                "name": "Attach",
            "type": "go",
            "request": "attach",
            "mode": "remote",
            "remotePath": "",
            "port":2345,
            "host":"127.0.0.1",
            "showLog": true,
            "trace": "log",
            "logOutput": "rpc"
        } 
    ]
}

6. Start Teleport with dlv

$ DLV=/home/developer/go/bin/bin/dlv
$ sudo $DLV --listen=:2345 --headless=true --api-version=2 --accept-multiclient exec ./build/teleport start
API server listening at: [::]:2345

7. Return to VSCode and Start Attach

Set a breakpoint in function CheckAndSetDefaults in lib/auth/resetpasswordtoken.go or another location you're interested in.

Start the Attach launch configuration. You may need to do Restart on the debug menu to start Teleport.

8. Create a user and then reset

sudo ./build/tctl users add jeff
sudo ./build/tctl users reset jeff

The breakpoint will be triggered.

Step through or continue.

9. Ready to exit

When you're ready to exit

$ dlv connect :2345
Type 'help' for list of commands.
(dlv) quit
Would you like to kill the headless instance? [Y/n] y

Additional:

If you'd like to run or debug from VSCode directly you can configure other launch configurations.

        {
            "name": "TshLogin",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${fileDirname}",
            "env": {},
            "args": ["login",  "--proxy=teleport.example.com"]           
        }

Open the tool/tsh/tsh.go and run this Launch configuration.