Merge pull request #30 from codefori/debuggerUpdate

Debugger documentation update

Author: sebjulliand

.astro/types.d.ts

@@ -391,5 +391,5 @@ declare module 'astro:content' {
 
 	type AnyEntryMap = ContentEntryMap & DataEntryMap;
 
-	export type ContentConfig = typeof import("../src/content/config.js");
+	export type ContentConfig = typeof import("./../src/content/config.js");
 }

src/content/docs/developing/debug/debug10.png

@@ -55,13 +55,13 @@ To debug a program from the Object Browser, right-click on the program object an
 
 ## General requirements
 
-* PTFs
-* Certificates setup on the server
-   * created in `/QIBM/UserData/IBMiDebugService/certs` by default
-* IBM i Debug extension
-   * installed into Visual Studio Code
-* Local client certificate
-   * can be imported with the 'Import local certificate' command
+* PTFs (see below)
+* IBM i Debug extension ([marketplace](https://marketplace.visualstudio.com/items?itemName=IBM.ibmidebug))
+  * installed into Visual Studio Code
+* Debug Service Certificates setup
+  * created in `/QIBM/UserData/IBMiDebugService/certs` by default
+  * Debug Service certificate `debug_service.pfx`
+  * Debug Service client certificate `debug_service.crt`
 
 ## Required PTFs
 
@@ -92,69 +92,95 @@ After you have installed the PTFs, the connection inside of Visual Studio Code w
 ## Configuring & starting the service
 
 <CardGrid>
-
 <Card>
+After connecting to a system in Code for IBM i, you can hover over the connection in the bottom status bar to check the Debugger version and status. The status will be `on` if both the Debug Server and Debug Service are running.
+</Card>
+<Card>
+![](./debug6.png)
+</Card>
+</CardGrid>
+<CardGrid>
+<Card>
+Clicking on the Debugger status will take you to the IBM i Debugger view. This view shows the status of the Debug Server and the Debug Service. It also allows to start/stop the Debug Server and manage the Debug Service.
+</Card>
+<Card>
+![](./debug7.png)
+</Card>
+</CardGrid>
 
-After connecting to a system in Code for IBM i, if the PTFs are installed but the service is not configured (i.e. the certificates don't exist) you will see a notice asking if you'd like to open the Walkthrough to configure the Debug Service. Clicking the button will open the Walkthrough.
-
-</Card><Card>
-
-![](./setup1.png)
-
-</Card></CardGrid>
+### Start/stop the Server and Service
+<CardGrid>
+<Card>
+The start/stop/restart actions are located on the right of each status. Running one of these actions will refresh the statuses once it's done.
+</Card>
+<Card>
+![](./debug8.png)
+![](./debug9.png)
+</Card>
+</CardGrid>
 
 <Aside type="tip">
-   There only needs to be one instance of the Debug Service running and therefore the certificates should only be generated once. All developers share the Debug Service.
+   Starting and stopping the Debug Server and Service requires the *ALLOBJ special authority.
 </Aside>
 
----
-
-### Generating certificates
-
+### Managing the Debug Service
 <CardGrid>
-
 <Card>
+If the Debug Service is not correctly configured, a warning sign will appear next to it. Expanding the Debug Service node will show the cause of the issue.
+</Card>
+<Card>
+![](./debug10.png)
+![](./debug11.png)
+</Card>
+</CardGrid>
 
-This Walkthrough can easily configure the Debug Service and start it up. The last steps have buttons to 'Generate certificates' and 'Start debug service'. Running them in order will do all the work to setup the service.
-
-*It will ask you to confirm the initialisation.*
-
-If certificates already exist on the server, you may see a slightly different message as Code for IBM i will not replace existing certificates.
-
-</Card><Card>
+<Aside type="tip">
+   There only needs to be one instance of the Debug Service running and therefore the certificates should only be generated once. All developers share the Debug Service.
+</Aside>
 
-![](./setup2_a.png)
+#### Generating certificates
+The Debug Service needs a certificate to be able to be started. This is required because the Debug Service is basically a web server exposing web services through HTTPS, and encrypting the traffic on HTTPS requires a certificate. Supported formats for the certificate are `PKCS12` and `JKS`. If Code for IBM i is used to generate the certificate, it will use the PKCS12 format.
 
-</Card></CardGrid>
+By default, certificates are generated in `/QIBM/UserData/IBMiDebugService/certs` (which is the recommended location). The path to the Debug Service certificate is set in `/QIBM/ProdData/IBMiDebugService/bin/DebugService.env` with `DEBUG_SERVICE_KEYSTORE_FILE`.
 
----
+The Debug Service certificate can only be generated if it's missing. In this case, the IBM i Debugger view will show this error:
 
-### Starting the server
+![](./debug10.png)
 
-<CardGrid>
+Clicking on the Setup Service Certificate button will start a process that offers to either generate a certificate or import an existing one (`PKCS12` format only). Once the certificate is successfully generated or imported, two files will be found under `/QIBM/UserData/IBMiDebugService/certs`:
+* `debug_service.pfx`
+  * the Debug Service certificate, used by the service to encrypt the communication.
+* `debug_service.crt`
+  * the client certificate that clients must download if the `Secure Debug` option is turned on in Code for IBM i.
 
-<Card>
+If these certificates are deleted for some reason, they can be simply regenerated from the IBM i Debugger view as described above. They are used only to encrypt the traffic between the clients and Debug Service.
 
-The 'Start debug service' button will spin up the Debug Service. If the Debug Service is already running, it will ask you if you want to end the existing instance before starting a new one - this is a requirement if you have generated new certificates on the server. It is not recommended to run two instances of the Debug Service at once.
+If `Secure Debug` is on and the client certificate cannot be found locally or does not match the remote certificate, Code for IBM i will show a warning in the IBM i Debugger view and offer an action to import the client certificate.
 
-</Card><Card>
+![](./debug11.png)
 
-![](./setup3_a.png)
 
-</Card></CardGrid>
+#### Starting the Debug Service from Code for IBM i
+Starting the Debug Service can be done from the IBM i Debugger view and requires `*ALLOBJ` special authority.
 
-<CardGrid>
+![](./debug12.png)
 
-<Card>
+Clicking on the action to start the Service will first show a prompt showing `SBMJOB` parameters. Since the shell script that starts the service will be submitted, this lets you modify the submission parameters if needed. Only the `CMD` and `JOB` parameters are imposed.
 
-You can also start the Debug Service through the command palette:
+![](./debug13.png)
 
-</Card><Card>
+Once the prompt is validated, the SBMJOB command will be executed and Code for IBM i will monitor its execution until the Debug Service is actually started (or fails to start).
 
-![](./setup3_b.png)
+#### Starting the Debug Service outside of Code for IBM i
+If the Debug Service was configured from Code for IBM i (i.e the certificate was generated from Code for IBM i), then it is possible to start the Debug Service by running the same `SBMJOB` command that Code for IBM i uses:
 
-</Card></CardGrid>
+```
+SBMJOB CMD(STRQSH CMD('/QOpenSys/pkgs/bin/bash -c /QIBM/ProdData/IBMiDebugService/bin/startDebugService.sh')) JOB(DBGSVCE) JOBQ(QSYS/QUSRNOMAX) JOBD(QSYS/QSYSJOBD) USER(*CURRENT)
+```
 
+<Aside type="tip">
+   This will only work if Code for IBM i was used to configure the Service and generate its certificate.
+</Aside>
 ---
 
 ## Debug Service ports