[Filebeat] Update docs for unix sockets

[andrewstucki]

What does this PR do?

Adds in forgotten documentation about new Unix socket support as well as marks the inputs as beta, per #17492 (comment).

[elasticmachine]

Pinging @elastic/siem (Team:SIEM)

[andrewkroh]

It would be good to document some of the behavior. Like must the file exist when the input starts? What are the file permission requirements?

[andrewstucki]

So, unix socket behavior is generally kind of tricky. If the file descriptor used for controlling the socket lifecycle is already on the filesystem, we'll actually get an error trying to bind. Additionally, go will actually unlink the fd automatically when the socket is closed. So WDYT about something like:

The file specified under the path argument, must not exist prior to using this input. If filebeat is not cleanly shut down and you see an error starting filebeat specifying "bind: address already in use", remove the file specified at path and restart filebeat.

[andrewkroh]

So Filebeat controls the creation and destruction? Perhaps Filebeat should automatically unlink it to try to resolve there error without user intervention.

What will the file mode be of the created unix socket? What permissions will be needed by the writing app?

[andrewstucki]

So, ideally filebeat would fully control the lifecycle, but I hesitate to unlink any file that a user specifies in a configuration at startup time.

AFAIK unix sockets are always created with 755 by the underlying OS. So their permissions look like srwxr-xr-x with the s indicator saying that this is actually a reference to a socket fd.

If you feel strongly about the attempted os.Remove call at startup I can add that, but I think we'd want to put a bolded section in the docs saying, "make sure that no file exists with this path, otherwise it'll be removed"

[andrewkroh]

There is some precedence for removing the socket if it exists in libbeat. But one thing I would add is a stat call to check if it is a socket before removing it.

I think you're right with 755 for when filebeat is running as root as a service since the default umask is 0022 for root and for systemd. So this means that only root users can pass logs to Filebeat in most deployments. I would explain this so users understand the permission requirements.

Users will probably ask for a way to configure the mode and/or the group of the socket. So they don't have to run their app as root.

[andrewstucki]

👍 added the cleanup code with a refusal error if the file isn't a socket. Also added some permission modification code to address the permissions issue.

[andrewkroh]

I was thinking this through a little more while reviewing your changes. Maybe a better route is to only allow chgrp and chmod changes. chgrp works for unprivileged users (with restrictions to groups the user is a member of) whereas chown is only available to root. This would leave the owner of the socket intact which I think is nice too.

As a user I would probably create a filebeat-writers group on the system and configure Filebeat to chgrp the file to filebeat-writers and configure it to chmod it to 770 (or whatever the least privs are). Ideally it create the socket with these attributes so there's no chance of a race condition where the socket exists but it not accessible to the app that needs to use it.

chgrp (and chown) is current prohibited in Beats by a seccomp policy. You'll have to whitelist chgrp in order to allow it in the Filebeat process.

[andrewstucki]

Sounds good, modified the implementation to only use chown with a gid set and chmod -- WRT creating the fd with the proper umask--from the looks of golang/go#11822 our only two options are doing a syscall.Umask prior to the call to Listen which is going to affect all files created by the process or changing it after the fact. So, I figure changing the file mode after the fact is probably the lesser of the two evils.

[andrewkroh]

I would say to use chgrp so we can be finer grained in our seccomp policy but it looks like chgrp isn't currently exposed in any readily available Go API. So LGTM.

[andrewkroh]

LGTM