Installing H@H on Debian or Ubuntu - Revision history

Bipface: systemctl enable hath

2020-04-10T20:22:15Z

systemctl enable hath

← Older revision		Revision as of 20:22, 10 April 2020
Line 103:		Line 103:
	(The line <code>SuccessExitStatus=143</code> is needed because the Java process may return a non-zero exit code even after a graceful shutdown).		(The line <code>SuccessExitStatus=143</code> is needed because the Java process may return a non-zero exit code even after a graceful shutdown).

	Now start the service:		Now enable and start the service:
	<pre># systemctl start hath</pre>		<pre># systemctl enable hath
			# systemctl start hath</pre>

	==Listening on Port 443==		==Listening on Port 443==

Bipface: make clear the mutually-exclusive options for port 443

2020-03-21T12:22:25Z

make clear the mutually-exclusive options for port 443

← Older revision		Revision as of 12:22, 21 March 2020
Line 114:		Line 114:
	Before proceeding, stop the H@H service (<code># systemctl stop hath</code>) and configure your client to use port 443 on the [https://e-hentai.org/hentaiathome.php Hentai@Home Clients] page.		Before proceeding, stop the H@H service (<code># systemctl stop hath</code>) and configure your client to use port 443 on the [https://e-hentai.org/hentaiathome.php Hentai@Home Clients] page.

	===Using POSIX Capabilities===		===Option 1: Using POSIX Capabilities===

	The easiest solution is to enable the corresponding ''capability'' on the Java binary.		The easiest solution is to enable the corresponding ''capability'' on the Java binary.
Line 130:		Line 130:
	Note that this approach may not be suitable if your system is using Java for other purposes as well. ''Capabilities'' have been known to cause adverse effects in some cases, so be sure to test any other Java applications present on your system.		Note that this approach may not be suitable if your system is using Java for other purposes as well. ''Capabilities'' have been known to cause adverse effects in some cases, so be sure to test any other Java applications present on your system.

	===Using Network Address Translation (NAT)===		===Option 2: Using Network Address Translation (NAT)===

	Alteratively, ''network address translation'' can redirect traffic from your internet-facing port 443 to your H@H client listening on a non-privileged port.		Alteratively, ''network address translation'' can redirect traffic from your internet-facing port 443 to your H@H client listening on a non-privileged port.

Bipface: add section 'Listening on Port 443'

2020-03-21T12:20:26Z

add section 'Listening on Port 443'

← Older revision		Revision as of 12:20, 21 March 2020
Line 104:		Line 104:

	Now start the service:		Now start the service:
			<pre># systemctl start hath</pre>

			==Listening on Port 443==

			H@H will work on most port numbers, however making it accessible on port 443 is recommended as more users will be able to connect to it.<br>On Linux, ports numbers below 1024 are considered ''privileged''. Additional steps are required in order for H@H to utilise ports in the privileged range.

			There are multiple options for achieving this. The most common approaches are as follows.

			Before proceeding, stop the H@H service (<code># systemctl stop hath</code>) and configure your client to use port 443 on the [https://e-hentai.org/hentaiathome.php Hentai@Home Clients] page.

			===Using POSIX Capabilities===

			The easiest solution is to enable the corresponding ''capability'' on the Java binary.

			Firstly ensure the <code>setcap</code> utility is installed, by running:
			<pre># apt install libcap2-bin</pre>

			Next, [[#Defining the H@H Service\|edit the H@H unit file]] again, and add the following line in the <code>[Service]</code> section:
			<pre>ExecStartPre=+/bin/sh -c 'setcap "cap_net_bind_service=+ep" "$(readlink -f /usr/bin/java)"'</pre>
			This will ensure that the Java binary can bind to privileged ports before launching the H@H client.

			Now start the service again:
			<pre># systemctl start hath</pre>

			Note that this approach may not be suitable if your system is using Java for other purposes as well. ''Capabilities'' have been known to cause adverse effects in some cases, so be sure to test any other Java applications present on your system.

			===Using Network Address Translation (NAT)===

			Alteratively, ''network address translation'' can redirect traffic from your internet-facing port 443 to your H@H client listening on a non-privileged port.

			Start by [[#Defining the H@H Service\|editing the H@H unit file]] again, and replacing the <code>ExecStart</code> line with:
			<pre>ExecStart=/usr/bin/java -jar HentaiAtHome.jar --port=1024</pre>
			Where <code>1024</code> is a port of your choice in the range 1024–65535.

			If your system is behind a router/firewall, you most likely have a port-forwarding rule configured already to make your server accessible from the internet. You'll need to modify this rule to direct traffic from external port 443 to the port selected in the previous step (on your server's local IP address).

			Another way to perform port redirection is to apply the following ''iptables'' rule on the server itself:
			<pre># iptables -A PREROUTING -t nat -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 1024</pre>
			Where <code>eth0</code> is the name of your network interface and <code>1024</code> is your selected port.

			Which approach you choose depends on the nature of your network, the features provided by your router, etc.

			Once the NAT rule is in place, start the service again:
	<pre># systemctl start hath</pre>		<pre># systemctl start hath</pre>

Bipface: /* Prerequisites */

2020-03-21T10:11:11Z

Prerequisites

← Older revision		Revision as of 10:11, 21 March 2020
Line 11:		Line 11:
	* One or more 'active' [https://e-hentai.org/hentaiathome.php Hentai@Home Clients] on your account.		* One or more 'active' [https://e-hentai.org/hentaiathome.php Hentai@Home Clients] on your account.

	* An open port through which the client can accept connections from the internet, as explained in the [[Hentai@Home#Minimum Requirements\|minimum requirements]] section~~.<br>In particular, you may need to choose a port number greater than 1023 to avoid having to run the client as root~~.<br>Check for firewall rules by running <code># iptables --list-rules</code>.		* An open port through which the client can accept connections from the internet, as explained in the [[Hentai@Home#Minimum Requirements\|minimum requirements]] section.<br>Check for firewall rules by running <code># iptables --list-rules</code>.

	* This guide assumes a server-style environment, typical of VPS/cloud-hosted systems. Installation on desktop or IoT systems, for example, may require doing some things differently.		* This guide assumes a server-style environment, typical of VPS/cloud-hosted systems. Installation on desktop or IoT systems, for example, may require doing some things differently.

Bipface: create page

2020-03-17T00:37:36Z

create page

New page

==Prerequisites==

* Basic familiarity with Linux.

* A server running '''Debian version 9''' (''Stretch'') or newer, or '''Ubuntu version 16''' (''Xenial Xerus'') or newer. To use earlier versions you will need to determine how to install a '''Java 8''' runtime, which may not be a straightforward process and is beyond the scope of this guide.

* Root access to your server (i.e. <code>su</code>/<code>sudo</code>).

* PuTTY or any other SSH program to connect to your server. This allows for copying/pasting of commands.

* One or more 'active' [https://e-hentai.org/hentaiathome.php Hentai@Home Clients] on your account.

* An open port through which the client can accept connections from the internet, as explained in the [[Hentai@Home#Minimum Requirements|minimum requirements]] section. In particular, you may need to choose a port number greater than 1023 to avoid having to run the client as root. Check for firewall rules by running <code># iptables --list-rules</code>.

* This guide assumes a server-style environment, typical of VPS/cloud-hosted systems. Installation on desktop or IoT systems, for example, may require doing some things differently.

===Optional Tools===

To perform the installation, you may also require the following:

* A command-line HTTP client such as <code>wget</code> or <code>curl</code>.

* A zip-file extractor such as <code>unzip</code>.

* A text editor such as <code>nano</code> or <code>vi</code>.

On some distributions, such as ''Minimal Ubuntu'', standard command-line tools might not be present by default. Use <code># apt install</code> to install these packages as needed.

===Take Note===

* Linux is case-sensitive with file names. Therefore, it is best to use lowercase names everywhere to make it easier for yourself.

* Commands starting with '''$''' are to be run as current user, those starting with '''#''' as root.

* Before installing packages, refresh the package manager by running <code># apt update</code>.

* H@H 1.6.0 and above uses SSL certificates. For them to work properly, you need the '''ntp''' package, which keeps the server's date and time in sync. It is normally installed by default.

==Overview==

At a glance, the steps to install H@H are as follows, with further details in the subsequent sections:

* Install a Java version 8 (or newer) runtime environment.

* Obtain and configure the latest H@H client software.

* Define a service (systemd ''unit file'') to run it.

==Installing Java==

Start by checking whether a Java runtime is already available by running:
<pre>$ java -version</pre>
A result such as <code>openjdk version "1.8.0_242"</code>, where the version number is 1.8 or greater, indicates that your server has a suitable Java runtime and you can skip to the next section.

If you see a result such as <code>java: command not found</code>, no Java runtime is installed yet.

Examine the default JRE package:
<pre># apt show default-jre-headless</pre>
You should expect to find a line in the output such as <code>Depends: '''openjdk-8'''-jre-headless, java-common</code>. If '''openjdk-7''' or lower is listed instead, your OS version may be too old to install a Java 8 runtime by conventional means — refer to the [[#Prerequisites|Prerequisites]] section.

Install the JRE:
<pre># apt install default-jre-headless</pre>
If you're planning to use H@H in GUI mode at any point, you should instead install the package <code>default-jre</code> (without the ''-headless'' suffix). Otherwise, the headless package will suffice.

Once complete, run <code>$ java -version</code> again to verify the result.

==Preparing the H@H Client==

It is recommended to create a dedicated service account to run the H@H client. This is achieved with the command:
<pre># adduser hath</pre>

Login as the newly created user, then download and extract the H@H client software: (Replace <code>VERSION</code> with the version number of the latest release, which can be found on the [https://e-hentai.org/hentaiathome.php Hentai@Home Clients] page)
<pre># login hath
$ wget 'https://repo.e-hentai.org/hath/HentaiAtHome_VERSION.zip'
$ unzip HentaiAtHome_VERSION.zip</pre>

Launch the client by running:
<pre>$ java -jar HentaiAtHome.jar</pre>
You should be prompted to enter your ''Client ID'' and ''Client Key'', which can be found on the [https://e-hentai.org/hentaiathome.php Hentai@Home Clients] page.

Once the client has successfully authenticated with the server, press <code>ctrl+C</code> to quit the client, then proceed to the next section.

==Defining the H@H Service==

Use the following command to create a new ''unit file'' defining the service:
<pre># systemctl edit hath.service --full --force</pre>

Insert the following text and save the file:
<pre>[Unit]
Description=Hentai@Home
After=local-fs.target remote-fs.target network.target

[Service]
Type=simple
User=hath
WorkingDirectory=/home/hath
SuccessExitStatus=143
ExecStart=/usr/bin/java -jar HentaiAtHome.jar
Restart=on-failure

[Install]
WantedBy=multi-user.target</pre>
(The line <code>SuccessExitStatus=143</code> is needed because the Java process may return a non-zero exit code even after a graceful shutdown).

Now start the service:
<pre># systemctl start hath</pre>

==Testing and Monitoring==

You can see the current status of your H@H service by running:
<pre># systemctl status hath</pre>
The output should indicate whether the service is active, and shows the last few lines of console output from the H@H process itself.

You can also read the two log files <code>log_out</code> and <code>log_err</code>, which are found in <code>/home/hath/log/</code>.

One way to confirm that the client is listening for connections is to open <code>https://ADDRESS:PORT/robots.txt</code> in a web browser, where <code>PORT</code> is the port number configured for the client and <code>ADDRESS</code> is the internet-facing IP address of your server. If the connection is established the browser will most likely present a HTTPS certificate error – bypass the error and a text file should be served to you.

==See also==
*[[Hentai@Home]]

[[Category:E-Hentai Galleries]]