'Onboarding using a file' documentation is incorrect

[nhinds]

The Onboarding using a file instructions in the documentation do not work. The user is instructed to run sudo service omsagent restart, but if the OMS agent is not onboarded during installation the omsagent service does not exist.

To reproduce on 64-bit Ubuntu 16.04:

1. Run sudo ./omsagent-1.2.0-148.universal.x64.sh --install on a machine without the OMS agent installed
2. Create /etc/omsagent-onboard.conf as per the documentation, by running sudo su omsagent vi /etc/omsagent-onboard.conf
3. Run sudo service omsagent restart as per the documentation

At step 2, running sudo su omsagent vi /etc/omsagent-onboard.conf results in an error:

$ sudo su omsagent vi /etc/omsagent-onboard.conf
/usr/bin/vi: /usr/bin/vi: cannot execute binary file

Trying variants of the command allows vi to run - e.g. sudo -su omsagent vi /etc/omsagent-onboard.conf (passing the -s and -u flags to sudo) or sudo su omsagent -c 'vi /etc/omsagent-onboard.conf' (passing vi /etc/omsagent-onboard.conf to su as the command to execute as the user) - however neither variant of the command allows the file to be created successfully as the omsagent does not have write permission to the /etc directory.

The instruction "Create the file /etc/omsagent-onboard.conf The file must be readable and writable for the user omsagent. sudo su omsagent vi /etc/omsagent-onboard.conf" probably needs to be split into two steps - first, create the file and make it readable (sudo touch /etc/omsagent-onboard.conf && sudo chown omsagent:omsagent /etc/omsagent-onboard.conf), second, edit the file (sudo -su omsagent vi /etc/omsagent-onboard.conf). Alternatively, perhaps the file should first be created as root (sudo vi /etc/omsagent-onboard.conf) and then made readable/writable by omsagent (sudo chown omsagent:omsagent /etc/omsagent-onboard.conf)

Once /etc/omsagent-onboard.conf is created, at step 3 running sudo service omsagent restart results in an error:

$ sudo service omsagent restart
Failed to restart omsagent.service: Unit omsagent.service not found.

During installation, the following warning is output: "Warning: Agent is not onboarded. omsagent cannot be registered as a service." This seems to indicate that the omsagent service will not exist until the agent is onboarded, so we can't use service omsagent restart to onboard the agent.

It appears from #185 that the correct instruction is cd <somewhere> && sudo ./service_control <something> - perhaps cd /opt/microsoft/omsagent/bin/ && sudo ./service_control restart, or just sudo /opt/microsoft/omsagent/bin/service_control restart

[nhinds]

I can't actually get any of the command variants from #185 to work to onboard the agent. All of the service_control options just result in "Warning: Agent is not onboarded. omsagent cannot be registered as a service."

[robbiezhang]

@nhinds Thank you! The document is out of date. We'll update it.
Basically, it should not call service omsagent start, but sudo /opt/microsoft/omsagent/bin/omsadmin.sh