Management pt BR

Gerenciamento

Esta seção abrange assuntos relacionados ao gerenciamento do processo do ASF de forma ideal. Embora não seja estritamente obrigatório para o uso, ele inclui várias dicas, truques e boas práticas que gostaríamos de compartilhar, especialmente para administradores de sistema, pessoas empacotando o ASF para uso em repositórios de terceiros, bem como usuários avançados e afins.

Serviço `systemd` para Linux

Nas variantes generic e linux, o ASF vem com o arquivo [email protected] que é um arquivo de configuração do serviço para o systemd. Se você quiser executar o ASF como um serviço, por exemplo, para executá-lo automaticamente após a inicialização do seu computador, então um serviço systemd adequado é provavelmente a melhor maneira de fazer isso, por isso, recomendamos fortemente ele ao invés de fazer o gerenciamento sozinho através do nohup, screen ou similar.

Firstly, create the account for the user you want to run ASF under, assuming it doesn't exist yet. We'll use asf user for this example, if you decided to use a different one, you'll need to substitute asf user in all of our examples below with your selected one. Our service does not allow you to run ASF as root, since it's considered a bad practice.

su # Or sudo -i, to get into root shell
useradd -m asf # Create account you intend to run ASF under

Next, unpack ASF to /home/asf/ArchiSteamFarm folder. The folder structure is important for our service unit, it should be ArchiSteamFarm folder in your $HOME, so /home/<user>. If you did everything correctly, there will be /home/asf/ArchiSteamFarm/[email protected] file existing. If you're using linux variant and didn't unpack the file on Linux, but for example used file transfer from Windows, then you'll also need to chmod +x /home/asf/ArchiSteamFarm/ArchiSteamFarm.

We'll do all below actions as root, so get to its shell with su or sudo -i.

Firstly it's a good idea to ensure that our folder still belongs to our asf user, chown -hR asf:asf /home/asf/ArchiSteamFarm executed once will do it. The permissions could be wrong e.g. if you've downloaded and/or unpacked the zip file as root.

Secondly, if you're using generic variant of ASF, you need to ensure dotnet command is recognized and within one of the standard locations: /usr/local/bin, /usr/bin or /bin. This is required for our systemd service which executes dotnet /path/to/ArchiSteamFarm.dll command. Check if dotnet --info works for you, if yes, type command -v dotnet to find out where it's located. If you've used official installer, it should be in /usr/bin/dotnet or one of the two other locations, which is alright. If it's in custom location such as /usr/share/dotnet/dotnet, create a symlink for it using ln -s "$(command -v dotnet)" /usr/bin/dotnet. Now command -v dotnet should report /usr/bin/dotnet, which will also make our systemd unit work. If you're using OS-specific variant, you don't need to do anything in this regard.

Next, execute ln -s /home/asf/ArchiSteamFarm/ArchiSteamFarm\@.service /etc/systemd/system/ArchiSteamFarm\@.service, this will create a symbolic link to our service declaration and register it in systemd. Symbolic link will allow ASF to update your systemd unit automatically as part of ASF update - depending on your situation, you may want to use that approach, or simply cp the file and manage it yourself however you'd like.

Afterwards, ensure that systemd recognizes our service:

systemctl status ArchiSteamFarm@asf

○ [email protected] - ArchiSteamFarm Service (on asf)
     Loaded: loaded (/etc/systemd/system/[email protected]; disabled; vendor preset: enabled)
     Active: inactive (dead)
       Docs: https://github.com/JustArchiNET/ArchiSteamFarm/wiki

Pay special attention to the user we declare after @, it's asf in our case. Our systemd service unit expects from you to declare the user, as it influences the exact place of the binary /home/<user>/ArchiSteamFarm, as well as the actual user systemd will spawn the process as.

If systemd returned output similar to above, everything is in order, and we're almost done. Now all that is left is actually starting our service as our chosen user: systemctl start ArchiSteamFarm@asf. Wait a second or two, and you can check the status again:

systemctl status ArchiSteamFarm@asf

● [email protected] - ArchiSteamFarm Service (on asf)
     Loaded: loaded (/etc/systemd/system/[email protected]; disabled; vendor preset: enabled)
     Active: active (running) since (...)
       Docs: https://github.com/JustArchiNET/ArchiSteamFarm/wiki
   Main PID: (...)
(...)

If systemd states active (running), it means everything went well, and you can verify that ASF process should be up and running, for example with journalctl -r, as ASF by default also writes to its console output, which is recorded by systemd. If you're satisfied with the setup you have right now, you can tell systemd to automatically start your service during boot, by executing systemctl enable ArchiSteamFarm@asf command. That's all.

If by any chance you'd like to stop the process, simply execute systemctl stop ArchiSteamFarm@asf. Likewise, if you want to disable ASF from being started automatically on boot, systemctl disable ArchiSteamFarm@asf will do that for you, it's very simple.

Please note that, as there is no standard input enabled for our systemd service, you won't be able to input your details through the console in usual way. Running through systemd is equivalent to specifying Headless: true setting and comes with all its implications. Fortunately for you, it's very easy to manage your ASF through ASF-ui, which we recommend in case you need to supply additional details during login or otherwise manage your ASF process further.

Environment variables

It's possible to supply additional environment variables to our systemd service, which you'll be interested in doing in case you want to for example use a custom --cryptkey command-line argument, therefore specifying ASF_CRYPTKEY environment variable.

In order to provide custom environment variables, create /etc/asf folder (in case it doesn't exist), mkdir -p /etc/asf. We recommend to chown -hR root:root /etc/asf && chmod 700 /etc/asf to ensure that only root user has access to read those files, because they might contain sensitive properties such as ASF_CRYPTKEY. Afterwards, write to a /etc/asf/<user> file, where <user> is the user you're running the service under (asf in our example above, so /etc/asf/asf).

The file should contain all environment variables that you'd like to provide to the process. Those that do not have a dedicated environment variable, can be declared in ASF_ARGS:

# Declare only those that you actually need
ASF_ARGS="--no-config-migrate --no-config-watch"
ASF_CRYPTKEY="my_super_important_secret_cryptkey"
ASF_NETWORK_GROUP="my_network_group"

# And any other ones you're interested in

Overriding part of the service unit

Thanks to the flexibility of systemd, it's possible to overwrite part of ASF unit while still preserving the original unit file and allowing ASF to update it for example as part of auto-updates.

In this example, we'd like to modify default ASF systemd unit behaviour from restarting only on success, to restarting also on fatal crashes. In order to do so, we'll override Restart property under [Service] from default of on-success to always. Simply execute systemctl edit ArchiSteamFarm@asf, naturally replacing asf with the target user of your service. Then add your changes as indicated by systemd in proper section:

### Editing /etc/systemd/system/[email protected]/override.conf
### Anything between here and the comment below will become the new contents of the file

[Service]
Restart=always

### Lines below this comment will be discarded

### /etc/systemd/system/[email protected]
# [Install]
# WantedBy=multi-user.target
# 
# [Service]
# EnvironmentFile=-/etc/asf/%i
# ExecStart=dotnet /home/%i/ArchiSteamFarm/ArchiSteamFarm.dll --no-restart --process-required --service --system-required
# Restart=on-success
# RestartSec=1s
# SyslogIdentifier=asf-%i
# User=%i
# (...)

And that's it, now your unit acts the same as if it had only Restart=always under [Service].

Of course, alternative is to cp the file and manage it yourself, but this allows you for flexible changes even if you decided to keep original ASF unit, for example with a symlink.

Never run ASF as administrator!

ASF includes its own validation whether the process is being run as administrator (root) or not. Running as root is not required for any kind of operation done by the ASF process, assuming properly configured environment it's operating in, and therefore should be regarded as a bad practice. This means that on Windows, ASF should never be executed with "run as administrator" setting, and on Unix ASF should have a dedicated user account for itself, or re-use your own in case of a desktop system.

For further elaboration on why we discourage running ASF as root, refer to superuser and other resources. Se você ainda não estiver convencido, pergunte-se o que aconteceria com seu computador se o processo do ASF executasse o comando rm -rf /* logo após ser iniciado.

I run as `root` because ASF can't write to its files

This means that you have wrongly configured permissions of the files ASF is trying to access. You should login as root account (either with su or sudo -i) and then correct the permissions by issuing chown -hR asf:asf /path/to/ASF command, substituting asf:asf with the user that you'll run ASF under, and /path/to/ASF accordingly. If by any chance you're using custom --path telling ASF user to use the different directory, you should execute the same command again for that path as well.

After doing that, you should no longer get any kind of issue related to ASF not being able to write over its own files, as you've just changed the owner of everything ASF is interested in to the user the ASF process will actually run under.

I run as `root` because I don't know how to do it otherwise

su # Or sudo -i, to get into root shell
useradd -m asf # Create account you intend to run ASF under
chown -hR asf:asf /path/to/ASF # Ensure your new user has access to the ASF directory
su asf -c /path/to/ASF/ArchiSteamFarm # Or sudo -u asf /path/to/ASF/ArchiSteamFarm, to actually start the program under your user

That would be doing it manually, it's much easier to use our systemd service explained above.

I know better and I still want to run as `root`

ASF doesn't forcefully stop you from doing so, only displays a warning with a short notice. Just don't be shocked if one day due to a bug in the program it'll blow up your whole OS with complete data loss - you've been warned.

Múltiplas instâncias

O ASF permite a execução de múltiplas instâncias do processo no mesmo computador. The instances can be completely standalone or derived from the same binary location (in which case, you want to run them with different --path command-line argument).

Quando estiver executando várias instâncias do mesmo executável certifique-se que você desativou as atualizações automáticas em todas as configurações, pois não existe nenhuma sincronização entre eles no que tange as atualizações automáticas. Se você quiser continuar com as atualizações automáticas habilitadas nós recomendamos rodar instâncias individuais, mas você ainda pode fazer as atualizações funcionarem, contanto que você possa garantir que todas as outras instâncias do ASF sejam fechadas.

O ASF fará o seu melhor para manter uma quantidade mínima de comunicação entre Sistema Operacional e multi-processos com outras instâncias do ASF. This includes ASF checking its configuration directory against other instances, as well as sharing core process-wide limiters configured with *LimiterDelay global config properties, ensuring that running multiple ASF instances will not cause a possibility to run into a rate-limiting issue. No que diz respeito a aspectos técnicos, todas as plataformas usam nosso mecanismo dedicado de bloqueios baseado em arquivos personalizados do ASF criados em uma pasta temporária em C:\Users\<SeuUsuário>\AppData\Local\Temp\ASF no Windows e /tmp/ASF no Unix.

Não é necessário que instâncias do ASF compartilhem as mesmas propriedades *LimiterDelay, elas podem usar valores diferentes já que cada ASF adicionará seu próprio atraso configurado para o tempo de liberação após adquirir o bloqueio. Se a configuração *LimiterDelay estiver definida como 0, a instância do ASF vai pular a espera pelo bloqueio de determinado recurso que for compartilhado com outras instâncias (isso poderia manter um bloqueio compartilhado uns com os outros). Quando definido como outro valor, o ASF irá sincronizar corretamente com outras instâncias e esperar pela sua vez e liberar o bloqueio após o atraso configurado, permitindo que outras instâncias continuem.

O ASF leva em conta a configuração WebProxy quando decide sobre o escopo compartilhado, o que significa que duas instâncias do ASF usando configurações WebProxy diferentes não compartilharão seus limitadores entre si. Isso foi implementado para permitir que as configurações de WebProxy operem sem atrasos excessivos, como esperado de diferentes interfaces de rede. This should be good enough for majority of use cases, however, if you have a specific custom setup in which you're e.g. routing requests yourself in a different way, you can specify network group yourself through --network-group command-line argument, which will allow you to declare ASF group that will be synchronized with this instance. Tenha em mente que grupos de rede personalizados são exclusividades, o que significa que o ASF não vai mais usar o WebProxy para determinar o grupo certo, já que você é responsável pelo agrupamento nesse caso.

If you'd like to utilize our systemd service explained above for multiple ASF instances, it's very simple, just use another user for our ArchiSteamFarm@ service declaration and follow with the rest of the steps. This will be equivalent of running multiple ASF instances with distinct binaries, so they can also auto-update and operate independently of each other.