Documentation issue: falcon_install says that it needs falcon_configure to start the sensor but does not explain how

[kkeane]

The README for falcon_install says "To configure and start the sensor, please use the falcon_configure role after the sensor is installed."

But the README to falcon_configure does not explain how to use it to start the sensor.

Through trial and error, I found that setting the CID will start the sensor. That should be explicitly explained.

This behavior is also somewhat unexpected because all the required information should already be available from falcon_install.

[carlosmmatos]

@kkeane thanks for opening up this issue - just so I understand your request, you are asking if we can clarify:

• Falcon Configure role should state that for Linux/Mac you need to specify the CID in order to start the sensor

  Fair enough, it's documented in our official docs but we can definitely call that out.

The reason this is not available from the falcon_install role for linux/mac and the reason we split it out rather than having a generic falcon_install role that tries to do everything (install/config) was because of the way the installers work. There is an install of the packages + an additional configuration step. Whereas windows installer can't be installed without a CID being applied. It also allows for easier golden image creations as a lot of existing users simply want to install the sensor and then create a image that can be spun up and "post-configured". This prevents duplicate AIDs. It's basically more flexible this way currently.

Now this is not to say that in the future this workflow might change to allow more flexibility in the install role (the assumption being no additional configurations needed outside of applying CID and starting the sensor). So if you feel like this approach would be beneficial, I would say to open up an issue and be as specific as possible to what you would like to see.

[kkeane]

Wow, thanks for that quick response! My main issue was that the information about starting the sensor may have been there, but when you are new to falcon, I wouldn't even know where to look. Thanks for considering to improve that in the documentation! On separating installer and configuration - that makes sense, architecturally (and is documented well). What was confusing for me was two things. Just take it as feedback from a falcon newbie. First, I would have expected that the installer not just installs the RPM, but also installs (i.e., stores) the credentials. Of course I'm assuming that the sensor is going to need those credentials on an ongoing basis for API access anyway. If the OAuth credentials are strictly transactional, then it makes sense. Second, it is confusing (intuitively, even though that was documented) that merely providing the OAuth credentials without anything else has fairly important side effects. Sent with [Proton Mail](https://proton.me/) secure email.

…

On Tuesday, June 11th, 2024 at 4:10 PM, Carlos Matos ***@***.***> wrote: ***@***.***(https://github.com/kkeane) thanks for opening up this issue - just so I understand your request, you are asking if we can clarify: - Falcon Configure role should state that for Linux/Mac you need to specify the CID in order to start the sensor > Fair enough, it's documented in our official [docs](https://falcon.crowdstrike.com/login/?unilogin=true&next=/documentation/page/cba4f917/deploy-falcon-sensor-for-linux-using-cli#d5c077ef) but we can definitely call that out. The reason this is not available from the falcon_install role for linux/mac and the reason we split it out rather than having a generic falcon_install role that tries to do everything (install/config) was because of the way the installers work. There is an install of the packages + an additional configuration step. Whereas windows installer can't be installed without a CID being applied. It also allows for easier golden image creations as a lot of existing users simply want to install the sensor and then create a image that can be spun up and "post-configured". This prevents duplicate AIDs. It's basically more flexible this way currently. Now this is not to say that in the future this workflow might change to allow more flexibility in the install role (the assumption being no additional configurations needed outside of applying CID and starting the sensor). So if you feel like this approach would be beneficial, I would say to open up an issue and be as specific as possible to what you would like to see. — Reply to this email directly, [view it on GitHub](#528 (comment)), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/AABY5OWPAWIUIRO5M26QUBLZG4OQZAVCNFSM6AAAAABJD6KEAGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNRRGEZTOMRRGA). You are receiving this because you were mentioned.Message ID: ***@***.***>

[carlosmmatos]

Understood and appreciate your feedback. Hopefully the following can help clarify:

• The API credentials are strictly transactional.
• No credentials are stored on the sensor itself. The sensor is started by verifying the CCID (customer ID w/ checksum).
• Each role has pretty decent (these things can always be updated) documentation surrounding API usage and variables associated with such. If there are things you think can be worded better or explained better, please open up an issue or feel free to submit a PR as well.
• Finally, remember that for linux/mac, the install/configure roles are independent of each other in a way.
  • For example, you don't need to provide API credentials to the falcon_configure role at all if you already know your falcon_cid. The same is also true for the falcon_uninstall role - you only need API credentials if you would like to remove_host from the console as this requires an API call.

You technically don't need API credentials for any of the roles - they are there as an option for you.
Let's say for example the following scenario matches:

• You have already downloaded the sensor and stored it in a shared drive accessible to your linux systems
• You already have your CCID (this is actually found in the same page where you would have downloaded the sensor file)

In the above scenario, you're playbook would look something like the following:

- hosts: all
  roles:
  - role: crowdstrike.falcon.falcon_install
    vars:
      falcon_install_method: file
      falcon_localfile_path: /shared/dir/falcon.rpm
  - role: crowdstrike.falcon.falcon_configure
    vars:
      falcon_cid: <YOUR CCID>

This gives you the flexibility to choose what kind of deployment you are after. Likewise, let's say you wanted the same install as above, but instead, you wanted the API to grab your CCID for you. Then your playbook would be:

- hosts: all
  roles:
  - role: crowdstrike.falcon.falcon_install
    vars:
      falcon_install_method: file
      falcon_localfile_path: /shared/dir/falcon.rpm
  - role: crowdstrike.falcon.falcon_configure
    vars:
      falcon_client_id: <API CLIENT ID>
      falcon_client_secret: <API CLIENT SECRET>

This is a much better approach than just setting your API Credentials at the playbook level giving access to all the roles. That may not be the intended outcome however this is an Ansible usage issue as opposed to the roles having unintended consequences.

Basically the API methods are here to make it easier to interact with the falcon platform without having to manually login and do something. That is also why we've added plenty of modules to the collection, to make it easier for you to interact programmatically with falcon and create your own workflows. This is no different that using the aws collection, where you get to determine how to use the modules. Same concept applies here, except that we've created some roles around these modules to make it a little easier for consumers to use.

Hope this helps!