Merge branch 'akitasoftware:main' into main

Author: postman-insights-builds[bot]

cmd/internal/ec2/README.md

@@ -0,0 +1,36 @@
+### Amazon EC2/ Linux Server
+
+### Introduction
+
+- The Postman Live Collection Agent (LCA) runs as a systemd service on your server
+- The Postman collection is populated with endpoints observed from the traffic arriving at your service.
+
+### Prerequisites
+
+- Your server's OS supports `systemd`
+- `root` user
+
+### Usage
+
+- Log in as root user, or use `sudo su` to enable root before running the below command
+```
+POSTMAN_API_KEY=<postman-api-key> postman-lc-agent setup --collection <postman-collectionID>
+```
+
+To check the status or logs please use
+
+```
+journalctl -fu postman-lc-agent
+```
+
+#### Why is root required?
+
+- To enable and configure the agent as a systemd services
+- Env Configuration file location `/etc/default/postman-lc-agent`
+- Systemd service file location `/usr/lib/systemd/system/postman-lc-agent.service`
+
+### Uninstall
+
+- You can disable the systemd service using
+
+`sudo systemctl disable --now postman-lc-agent`

cmd/internal/ec2/add.go

@@ -0,0 +1,238 @@
+package ec2
+
+import (
+	"embed"
+	"os"
+	"os/exec"
+	"os/user"
+	"strings"
+	"text/template"
+
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/akitasoftware/akita-cli/printer"
+	"github.com/akitasoftware/akita-cli/telemetry"
+	"github.com/pkg/errors"
+)
+
+const (
+	envFileName         = "postman-lc-agent"
+	envFileTemplateName = "postman-lc-agent.tmpl"
+	envFileBasePath     = "/etc/default/"
+	envFilePath         = envFileBasePath + envFileName
+
+	serviceFileName     = "postman-lc-agent.service"
+	serviceFileBasePath = "/usr/lib/systemd/system/"
+	serviceFilePath     = serviceFileBasePath + serviceFileName
+
+	// Output of command: systemctl is-enabled postman-lc-agent
+	// Refer: https://www.freedesktop.org/software/systemd/man/latest/systemctl.html#Exit%20status
+	enabled     = "enabled"                                                                               // exit code: 0
+	disabled    = "disabled"                                                                              // exit code: 1
+	nonExisting = "Failed to get unit file state for postman-lc-agent.service: No such file or directory" // exit code: 1
+)
+
+// Embed files inside the binary. Requires Go >=1.16
+
+//go:embed postman-lc-agent.service
+var serviceFile string
+
+// FS is used for easier template parsing
+
+//go:embed postman-lc-agent.tmpl
+var envFileFS embed.FS
+
+// Helper function for reporting telemetry
+func reportStep(stepName string) {
+	telemetry.WorkflowStep("Starting systemd conguration", stepName)
+}
+
+func setupAgentForServer(collectionId string) error {
+
+	err := checkUserPermissions()
+	if err != nil {
+		return err
+	}
+	err = checkSystemdExists()
+	if err != nil {
+		return err
+	}
+
+	err = configureSystemdFiles(collectionId)
+	if err != nil {
+		return err
+	}
+
+	err = enablePostmanAgent()
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func askToReconfigure() error {
+	var isReconfigure bool
+
+	printer.Infof("postman-lc-agent is already present as a systemd service\n")
+	printer.Infof("Helpful commands \n Check status: systemctl status postman-lc-agent \n Disable agent: systemctl disable --now postman-lc-agent \n Check Logs: journalctl -fu postman-lc-agent\n Check env file: cat %s \n Check systemd service file: cat %s \n", envFilePath, serviceFilePath)
+
+	err := survey.AskOne(
+		&survey.Confirm{
+			Message: "Overwrite old API key and Collection ID values in systemd configuration file with current values?",
+			Default: true,
+			Help:    "Any edits made to systemd configuration files will be over-written.",
+		},
+		&isReconfigure,
+	)
+	if !isReconfigure {
+		printer.Infof("Exiting setup \n")
+		os.Exit(0)
+		return nil
+	}
+	if err != nil {
+		return errors.Wrap(err, "failed to run reconfiguration prompt")
+	}
+	return nil
+}
+
+// Check is systemd service already exists
+func checkReconfiguration() error {
+
+	cmd := exec.Command("systemctl", []string{"is-enabled", "postman-lc-agent"}...)
+	out, err := cmd.CombinedOutput()
+
+	if err != nil {
+		if exitError, ok := err.(*exec.ExitError); ok {
+			exitCode := exitError.ExitCode()
+			if exitCode != 1 {
+				return errors.Wrapf(err, "Received non 1 exitcode for systemctl is-enabled. \n Command output:%s \n Please send this log message to [email protected] for assistance\n", out)
+			}
+			if strings.Contains(string(out), disabled) {
+				return askToReconfigure()
+			} else if strings.Contains(string(out), nonExisting) {
+				return nil
+			}
+		}
+		return errors.Wrapf(err, "failed to run systemctl is-enabled posman-lc-agent")
+	}
+	if strings.Contains(string(out), enabled) {
+		return askToReconfigure()
+	}
+	return errors.Errorf("The systemctl is-enabled command produced output this tool doesn't recognize: %q. \n Please send this log message to [email protected] for assistance\n", string(out))
+
+}
+
+func checkUserPermissions() error {
+
+	// Exact permissions required are
+	// read/write permissions on /etc/default/postman-lc-agent
+	// read/write permission on /usr/lib/system/systemd
+	// enable, daemon-reload, start, stop permission for systemctl
+
+	printer.Infof("Checking user permissions \n")
+	cu, err := user.Current()
+	if err != nil {
+		return errors.Wrapf(err, "could not get current user")
+	}
+	if !strings.EqualFold(cu.Name, "root") {
+		printer.Errorf("root user is required to setup systemd service and edit related files.\n")
+		return errors.Errorf("Please run the command again with root user")
+	}
+	return nil
+}
+
+func checkSystemdExists() error {
+	message := "Checking if systemd exists"
+	printer.Infof(message + "\n")
+	reportStep(message)
+
+	_, serr := exec.LookPath("systemctl")
+	if serr != nil {
+		printer.Errorf("We don't have support for non-systemd OS as of now.\n For more information please contact [email protected].\n")
+		return errors.Errorf("Could not find systemd binary in your OS.")
+	}
+	return nil
+}
+
+func configureSystemdFiles(collectionId string) error {
+	message := "Configuring systemd files"
+	printer.Infof(message + "\n")
+	reportStep(message)
+
+	err := checkReconfiguration()
+	if err != nil {
+		return err
+	}
+
+	// Write collectionId and postman-api-key to go template file
+
+	tmpl, err := template.ParseFS(envFileFS, envFileTemplateName)
+	if err != nil {
+		return errors.Wrapf(err, "systemd env file parsing failed")
+	}
+
+	data := struct {
+		PostmanAPIKey string
+		CollectionId  string
+	}{
+		PostmanAPIKey: os.Getenv("POSTMAN_API_KEY"),
+		CollectionId:  collectionId,
+	}
+
+	// Ensure /etc/default exists
+	cmd := exec.Command("mkdir", []string{"-p", envFileBasePath}...)
+	_, err = cmd.CombinedOutput()
+	if err != nil {
+		return errors.Wrapf(err, "failed to create %s directory\n", envFileBasePath)
+	}
+
+	envFile, err := os.Create(envFilePath)
+	if err != nil {
+		printer.Errorf("Failed to create systemd env file")
+		return err
+	}
+
+	err = tmpl.Execute(envFile, data)
+	if err != nil {
+		printer.Errorf("Failed to write values to systemd env file")
+		return err
+	}
+
+	// Ensure /usr/lib/systemd/system exists
+	cmd = exec.Command("mkdir", []string{"-p", serviceFileBasePath}...)
+	_, err = cmd.CombinedOutput()
+	if err != nil {
+		return errors.Wrapf(err, "failed to create %s directory", serviceFileBasePath)
+	}
+
+	err = os.WriteFile(serviceFilePath, []byte(serviceFile), 0600)
+	if err != nil {
+		printer.Errorf("failed to create %s file in %s directory with err %q \n", serviceFileName, serviceFilePath, err)
+		return err
+	}
+
+	return nil
+}
+
+// Starts the postman LCA agent as a systemd service
+func enablePostmanAgent() error {
+	message := "Enabling postman-lc-agent as a service"
+	reportStep(message)
+	printer.Infof(message + "\n")
+
+	cmd := exec.Command("systemctl", []string{"daemon-reload"}...)
+	_, err := cmd.CombinedOutput()
+	if err != nil {
+		return errors.Wrapf(err, "failed to run systemctl daemon-reload")
+	}
+	// systemctl start postman-lc-service
+	cmd = exec.Command("systemctl", []string{"enable", "--now", serviceFileName}...)
+	_, err = cmd.CombinedOutput()
+	if err != nil {
+		return errors.Wrapf(err, "faild to run systemctl enable --now")
+	}
+	printer.Infof("Postman LC Agent enabled as a systemd service. Please check logs using the below command \n")
+	printer.Infof("journalctl -fu postman-lc-agent \n")
+
+	return nil
+}

cmd/internal/ec2/ec2.go

@@ -0,0 +1,67 @@
+package ec2
+
+import (
+	"fmt"
+
+	"github.com/akitasoftware/akita-cli/cmd/internal/cmderr"
+	"github.com/akitasoftware/akita-cli/rest"
+	"github.com/akitasoftware/akita-cli/telemetry"
+	"github.com/akitasoftware/akita-cli/util"
+	"github.com/pkg/errors"
+	"github.com/spf13/cobra"
+)
+
+var (
+	// Mandatory flag: Postman collection id
+	collectionId string
+)
+
+var Cmd = &cobra.Command{
+	Use:          "setup",
+	Short:        "Add the Postman Live Collections Agent to the current server.",
+	Long:         "The CLI will add the Postman Live Collections Agent as a systemd service to your current server.",
+	SilenceUsage: true,
+	RunE:         addAgentToEC2,
+}
+
+var RemoveFromEC2Cmd = &cobra.Command{
+	Use:          "remove",
+	Short:        "Remove the Postman Live Collections Agent from EC2.",
+	Long:         "Remove a previously installed Postman agent from an EC2 server.",
+	SilenceUsage: true,
+	RunE:         removeAgentFromEC2,
+
+	// Temporarily hide from users until complete
+	Hidden: true,
+}
+
+func init() {
+	Cmd.PersistentFlags().StringVar(&collectionId, "collection", "", "Your Postman collection ID")
+	Cmd.MarkPersistentFlagRequired("collection")
+
+	Cmd.AddCommand(RemoveFromEC2Cmd)
+}
+
+func addAgentToEC2(cmd *cobra.Command, args []string) error {
+	// Check for API key
+	_, err := cmderr.RequirePostmanAPICredentials("The Postman Live Collections Agent must have an API key in order to capture traces.")
+	if err != nil {
+		return err
+	}
+
+	// Check collecton Id's existence
+	if collectionId == "" {
+		return errors.New("Must specify the ID of your collection with the --collection flag.")
+	}
+	frontClient := rest.NewFrontClient(rest.Domain, telemetry.GetClientID())
+	_, err = util.GetOrCreateServiceIDByPostmanCollectionID(frontClient, collectionId)
+	if err != nil {
+		return err
+	}
+
+	return setupAgentForServer(collectionId)
+}
+
+func removeAgentFromEC2(cmd *cobra.Command, args []string) error {
+	return fmt.Errorf("this command is not yet implemented")
+}

cmd/internal/ec2/postman-lc-agent.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=Postman Live Collections Agent
+Wants=network-online.target
+After=network-online.target NetworkManager.service systemd-resolved.service
+
+[Service]
+EnvironmentFile=/etc/default/postman-lc-agent
+# DO NOT CHANGE
+# "${FOO}" uses the arguement as is, while "$FOO" splits the string on white space 
+# Reference: https://www.freedesktop.org/software/systemd/man/systemd.service.html#Command%20lines
+ExecStart=/usr/bin/postman-lc-agent apidump --collection "${COLLECTION_ID}" --interfaces "${INTERFACES}" --filter "${FILTER}" "$EXTRA_APIDUMP_ARGS"
+
+[Install]
+WantedBy=multi-user.target

cmd/internal/ec2/postman-lc-agent.tmpl

@@ -0,0 +1,39 @@
+# Add your Postman API key below. For example:
+#
+#   POSTMAN_API_KEY=PMAC-XXXXXXX
+#
+# This is required.
+
+POSTMAN_API_KEY={{.PostmanAPIKey}}
+
+
+# Add your your Postman Live Collection ID. 
+#This is required.
+
+COLLECTION_ID={{.CollectionId}}
+
+# For example,
+#   COLLECTION_ID=1234567-890abcde-f123-4567-890a-bcdef1234567
+
+
+# INTERFACES is optional. If left blank, the agent will listen on all available
+# network interfaces.
+#
+# FILTER is optional. If left blank, no packet-capture filter will be applied.
+# For example
+#   INTERFACES=lo,eth0,eth1
+#   FILTER="port 80 or port 8080"
+#
+
+INTERFACES=
+FILTER=
+
+
+# Configure any extra arguments you wish to provide to the
+# 'postman-lc-agent apidump' command. For example,
+#
+#   EXTRA_APIDUMP_ARGS="--rate-limit 100"
+#
+# This is optional and can be left blank.
+
+EXTRA_APIDUMP_ARGS=