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

     1  # Cleartext XFCC Mode
     2  
     3  ## Introduction
     4  
     5  This sandbox demonstrates how to run Fleetspeak in 'cleartext xfcc 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 below)
    16  by configuring Envoy to do so. See the official
    17  [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.28.0/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html#envoy-v3-api-enum-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-forwardclientcertdetails)
    18  for more details.
    19  
    20  The setup in this sandbox with the Fleetspeak frontend running in cleartext xfcc
    21  mode would be useful for cases where the Fleetspeak server is operated behind an
    22  Envoy proxy that terminates the mTLS connection.
    23  
    24  ![Cleartext Header Mode](../diagrams/cleartextXfccMode_355.png "Cleartext XFCC Mode")
    25  
    26  ## Setup
    27  
    28  Before you run the commands below make sure that you successfully executed the
    29  steps outlined in the [setup instructions](../../sandboxes#setup-instructions).
    30  
    31  ## Bring up the test environment
    32  
    33  ```
    34  docker compose up --build -d
    35  
    36   ✔ Network cleartext-xfcc-mode_default                Created                                                                                                      0.1s
    37   ✔ Container cleartext-xfcc-mode-front-envoy-1        Started                                                                                                      0.1s
    38   ✔ Container cleartext-xfcc-mode-mysql-server-1       Healthy                                                                                                      0.1s
    39   ✔ Container cleartext-xfcc-mode-fleetspeak-server-1  Healthy                                                                                                      0.0s
    40   ✔ Container cleartext-xfcc-mode-fleetspeak-client-1  Started                                                                                                      0.0s
    41  ```
    42  
    43  ## Find the client id
    44  
    45  ```
    46  docker logs cleartext-xfcc-mode-fleetspeak-client-1
    47  # The output should look similar to the below
    48  
    49  # config.go:44] Read 1 trusted certificates.
    50  # manager.go:103] initial load of writeback failed (continuing): open /fleetspeak-client.state: no such file or directory
    51  # manager.go:165] Using new client id: **768dbfef556d2341**
    52  # 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
    53  services.go:146] Started service hello with config:
    54  #   name:"hello"  factory:"Daemon"  config:{[type.googleapis.com/fleetspeak.daemonservice.Config]:{argv:"/venv/FSENV/bin/python"  argv:"/config/hello.py"}}
    55  # system_service.go:251] Unable to get revoked certificate list: unable to retrieve file, last attempt failed with: failed with http response code: 404
    56  
    57  # Run the test app container
    58  docker run -it --name greeter --network cleartext-xfcc-mode_default -p 1337:1337 --rm greeter bash
    59  ```
    60  
    61  ## Run the test app
    62  
    63  ```
    64  # In the above find the client id and export it in a variable
    65  export CLIENT_ID=**768dbfef556d2341**
    66  
    67  # Start the test app, when it runs add your input and hit enter. You should see the string being ecohed.
    68  /venv/FSENV/bin/python ./greeter.py --client_id=$CLIENT_ID --fleetspeak_message_listen_address="0.0.0.0:1337" \
    69      --fleetspeak_server="fleetspeak-server:9091" --alsologtostderr
    70  ```
    71  
    72  ## Bring down the test environment
    73  
    74  ```
    75  docker compose down
    76  ```