github.com/google/fleetspeak@v0.1.15-0.20240426164851-4f31f62c1aea/sandboxes/cleartext-header-mode/README.md (about)

     1  # Cleartext Header Mode
     2  
     3  ## Introduction
     4  
     5  This sandbox demonstrates how to run Fleetspeak in 'cleartext header mode'.
     6  
     7  The Fleetspeak frontend (the server) is using the Fleetspeak client's
     8  certficiate to identify it by deriving the client id from the certficiate.
     9  
    10  In cases where the mTLS connection is terminated on a load balancer between the
    11  Fleetspeak client and the Fleetspeak server the client certificate has to be
    12  forwarded by other means.
    13  
    14  This sandbox demonstrates how this can be achieved by adding the certificate
    15  into an additional header (the `client_certificate_header` in the diagram
    16  below).
    17  
    18  Furthermore, this sandbox also demonstrates how the client certificate checksum
    19  (the `client_certificate_checksum_header` in the diagram below) that the load
    20  balancers provide can be used to verify that the certificate received in the
    21  additional header is the same that the load balancer received during the mTLS
    22  exchange. \
    23  Additional information on how the checksum is derived from the certificate can
    24  be
    25  [found here](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-mtls-17#section-3.1).
    26  
    27  The setup in this sandbox with the Fleetspeak frontend running in cleartext mode
    28  would be useful for cases where the Fleetspeak server is operated in a Service
    29  Mesh environment.
    30  
    31  ![Cleartext Header Mode](../diagrams/cleartextHeaderMode_355.png "Cleartext Header Mode")
    32  
    33  ## Setup
    34  
    35  Before you run the commands below make sure that you successfully executed the
    36  steps outlined in the [setup instructions](../../sandboxes#setup-instructions).
    37  
    38  ## Bring up the test environment
    39  
    40  ```
    41  docker compose up --build -d
    42  
    43   ✔ Network cleartext-header-mode_default                Created                                                                                                      0.1s
    44   ✔ Container cleartext-header-mode-front-envoy-1        Started                                                                                                      0.1s
    45   ✔ Container cleartext-header-mode-mysql-server-1       Healthy                                                                                                      0.1s
    46   ✔ Container cleartext-header-mode-fleetspeak-server-1  Healthy                                                                                                      0.0s
    47   ✔ Container cleartext-header-mode-fleetspeak-client-1  Started                                                                                                      0.0s
    48  ```
    49  
    50  ## Find the client id
    51  
    52  ```
    53  docker logs cleartext-header-mode-fleetspeak-client-1
    54  # The output should look similar to the below
    55  
    56  # config.go:44] Read 1 trusted certificates.
    57  # manager.go:103] initial load of writeback failed (continuing): open /fleetspeak-client.state: no such file or directory
    58  # manager.go:165] Using new client id: **768dbfef556d2341**
    59  # client.go:175] No signed service configs could be read; continuing: invalid signed services directory path: unable to stat path [/config/fleetspeak-client/services]: stat /config/fleetspeak-client/services: no such file or directory
    60  services.go:146] Started service hello with config:
    61  #   name:"hello"  factory:"Daemon"  config:{[type.googleapis.com/fleetspeak.daemonservice.Config]:{argv:"/venv/FSENV/bin/python"  argv:"/config/hello.py"}}
    62  # system_service.go:251] Unable to get revoked certificate list: unable to retrieve file, last attempt failed with: failed with http response code: 404
    63  
    64  # Run the test app container
    65  docker run -it --name greeter --network cleartext-header-mode_default -p 1337:1337 --rm greeter bash
    66  ```
    67  
    68  ## Run the test app
    69  
    70  ```
    71  # In the above find the client id and export it in a variable
    72  export CLIENT_ID=**768dbfef556d2341**
    73  
    74  # Start the test app, when it runs add your input and hit enter. You should see the string being ecohed.
    75  /venv/FSENV/bin/python ./greeter.py --client_id=$CLIENT_ID --fleetspeak_message_listen_address="0.0.0.0:1337" \
    76      --fleetspeak_server="fleetspeak-server:9091" --alsologtostderr
    77  ```
    78  
    79  ## Bring down the test environment
    80  
    81  ```
    82  docker compose down
    83  ```