.\"
.\" Copyright (c) 2021 Michael Gmelin
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 28, 2021
.Dt SIGNALD 7
.Os
.Sh NAME
.Nm %%PKGBASE%%
.Nd Daemon to facilitate communication via Signal Private Messenger
.Sh SYNOPSIS
.Nm pkg install %%PKGBASE%%
.Sh DESCRIPTION
.Em Signald
is an unofficial utility for interacting with Signal.
It is a Java based daemon that is running in the background and is
communicated to over a socket.
.Pp
This man page documents how the
.Fx
port is installed and how to get started.
It assumes that the %%PKGBASE%% package was already installed,
e.g., from the
.Fx
package repo as described in
.Sx SYNOPSIS .
.Sh GETTING STARTED
To enable and start the service, run as root
.Bd -literal -offset indent
service %%PKGBASE%% enable
service %%PKGBASE%% start
.Ed
.Pp
Check log output:
.Bd -literal -offset indent
cat /var/log/%%PKGBASE%%/%%PKGBASE%%.log
.Ed
.Pp
Install signaldctl, a command line tool that allows interacting with
the service:
.Bd -literal -offset indent
pkg install go
go install gitlab.com/signald/signald-go/cmd/signaldctl@latest
.Ed
.Sh LINKING A DEVICE
To link an existing device (phone), first enter
.Bd -literal -offset indent
~/go/bin/signaldctl account link
.Ed
.Pp
then do "Select Linked Devices -> Link New Device"
in the Signal smartphone app's menu and scan the QR code shown
on your terminal.
.Sh REGISTERING A DEVICE
.Em WARNING :
This disconnects other devices using the same MSISDN.
.Bl -bullet -compact
.It
Open your web browser and enable developer mode
.It
Go to
.Lk https://signalcaptchas.org/registration/generate.html
.It
Solve the captcha
.It
Depending on your browser you are redirected to a URL starting
with "signalcaptcha://" or it can be seen in the web developer
console - everything after "//" is the captcha.
.El
.Pp
Register your device using the captcha copied above:
.Bd -literal -offset indent
~/go/bin/signaldctl account register [msisdn] --captcha [captcha]
.Ed
.Pp
.Em msisdn
is your full mobile phone number with country code, e.g., +123456789.
.Pp
You will receive a text message containing a verification code on the
MSISDN specified in the registration call above.
Use this verification code
.Bd -literal -offset indent
~/go/bin/signaldctl account verify [msisdn] [code]
.Ed
.Pp
to complete the registration.
.Sh SENDING A MESSAGE
Use this command to send a message
.Bd -literal -offset indent
~/go/bin/signaldctl message send -a [msisdn_from] [msisdn_to] [msg]
.Ed
.Pp
You can also send a message to yourself when using a linked device,
which will show up in "Note to Self", but not cause a notification,
e.g.,
.Bd -literal -offset indent
~/go/bin/signaldctl message send -a +123456789 +123456789 "Beep beep"
.Ed
.Sh FILES
.Bl -tag -width ".Pa /var/run/signald/signald.sock" -compact
.It Pa /var/db/signald
Signald database.
.It Pa /var/log/signald/signald.log
Signald log output.
.It Pa /var/run/signald/signald.sock
Socket to communicate with signald,
.Em world writable .
.El
.Sh SEE ALSO
.Xr ports 7 ,
.Xr daemon 8 ,
.Xr service 8
.Pp
.Rs
.%B "Signald project website"
.%U https://signald.org
.Re
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Michael Gmelin Aq Mt grembo@FreeBSD.org .