fleetdm
Update messaging when creating Linux fleet-osquery .deb files
Problem
Upon successful creation of a fleet-osquery installer, fleetctl displays guidance for how to use the installer to add a device to Fleet.
Generating your fleetd agent...
Success! You generated fleetd at ~/Documents/fleet-osquery_1.31.0_amd64.deb
To add this device to Fleet, double-click to install fleetd.
To add other devices to Fleet, distribute fleetd using Chef, Ansible, Jamf, or Puppet. Learn how: https://fleetdm.com/learn-more-about/enrolling-hosts
However, for .deb installers, the directions to double-click are incorrect. A Linux user would use dpkg -i to install the .deb instead of double-clicking.
Potential solutions
Update the messaging in fleetctl to direct the user to use dpkg -I to add the host to Fleet.
What is the expected workflow as a result of your proposal?
A Linux user would use fleetctl to create a .deb installer. Upon successful creation, they would be given directions to use dpkg -i to add the host to Fleet instead of double-clicking.
Hey @ddribeiro, great catch.
Even though it's not workflow blocking, can you please surface this during the next feature fest on 2024-09-12? A copy change here, would be a really quick-win improvement.
I think the "double-click" comes from a macOS bias. We automatically pop open the file explorer when we create a fleetd package on a macOS host.
Also, when you get the chance, can you please record a quick Loom of the experience when creating fleetd on Linux? (.deb) Do we open some file explorer? Does Linux have one?
That would be really helpful for everyone's learning/understanding.
Problem
Upon successful creation of a fleet-osquery installer, fleetctl displays guidance for how to use the installer to add a device to Fleet.
Generating your fleetd agent...
Success! You generated fleetd at ~/Documents/fleet-osquery_1.31.0_amd64.deb
To add this device to Fleet, double-click to install fleetd.
To add other devices to Fleet, distribute fleetd using Chef, Ansible, Jamf, or Puppet. Learn how: https://fleetdm.com/learn-more-about/enrolling-hosts
However, for .deb installers, the directions to double-click are incorrect. A Linux user would use dpkg -i to install the .deb instead of double-clicking.
Potential solutions
Update the messaging in fleetctl to direct the user to use dpkg -I to add the host to Fleet.
What is the expected workflow as a result of your proposal?
A Linux user would use fleetctl to create a .deb installer. Upon successful creation, they would be given directions to use dpkg -i to add the host to Fleet instead of double-clicking.
- @noahtalerman: A copy change to make this more cross-platform friendly, would be a really quick-win improvement.
- We could go w/ "To add this host to Fleet, install fleetd." I think the "double-click" language comes from a macOS bias. We automatically pop open the file explorer when we create a fleetd package on a macOS host.
FYI @pintomi1989 we updated the fleetctl package output to make it more cross-platform:
We think this fulfills customer-cisneros's request. I think we can close this one. What do you think?
Hey @noahtalerman - I've reached out to the customer to verify if this satisfies their needs. I will follow up once I have a response back
Hey @noahtalerman - Feedback is that this is too vague. They responded suggesting the following:
If its a .deb, can we just have the text say "Install the .deb using dpkg -i
Just saying "Install fleetd" seems fairly vague
Could make it a bit more "generic" by saying "To add hosts to Fleet, install fleetd using your distributions preferred package manager, such as apt (Debian/Ubuntu) or dnf (Fedora/RHEL)" or something similar as well
@pintomi1989 great feedback. I opened a PR to the doc here: https://github.com/fleetdm/fleet/pull/27223/files
Now the "Learn more" link in the fleetctl package output (below) will navigate the user to this section in the guide: https://github.com/fleetdm/fleet/blob/0437d5f576a723298619aa9ee86378c75be29e4c/articles/enroll-hosts.md#install-fleetd
Hey @noahtalerman
Customer's response to this update was positive --> "I think that actually makes sense because its "generic" enough phrasing to apply to all OS's, and provides a single point of updating the documentation in case of any changes, rather than having to write different instructions per-OS (and per-file type on Linux)"
I will close this out
Creating Linux files, "Add this host to Fleet" invites, Cross-platform thrives.
