Advanced client operations: Hallmark, Token, Graceful stop, and Network Ports

[opticalc]

If you are on an internet connection that frequently changes its IP address, such as DSL, and in some cases, cable modem service, using this hallmark feature will become a headache, and all active peers will disappear when your IP address changes, and you will be unable to forge.  Your IP address for DSL changes every time your modem/router resets.  Some cable modems will change IP address when they are reset.

Hallmarks are a way for your node to prove to the p2p network that for the client running on a particular IP addres, you own the account you say you do (and thus do have the balance claimed)

The result is network protection against zombie hosts fuxxoring NXT up in an attack

Thus, hallmarks can be used to tie an account/balance to an IP address, so consider if this is OK for you.

These instructions assume that you only ever run 1 client for a particular account.

1. From the host that runs the NXT client, do web request to http://www.whatismyip.com and find out what your publicIP address is.  In order to be 100% sure the correct data gets returned, this web request must be sent from the host that runs the NXT client.  The IP address you get will be used for the MY_HOST field later on.

2. Do such a request: http://localhost:7874/nxt?requestType=markHost&secretPhrase=MY_SECRET&host=MY_HOST&weight=100&date=CURRENT_DATE where CURRENT_DATE is a date in "yyyy-mm-dd" notation.

3. Copy hallmark value (just the hexadecimal characters) into "myHallmark" field, just between these 2 tags: <param-value> and </param-value> in the file web.xml.  This file is in the nxt\webapps\root\WEB-INF\ directory.

4.  Copy the IP address you found from step 1 into the myAddress field, just between these 2 tags: <param-value> and </param-value> in the file web.xml.  This file is in the nxt\webapps\root\WEB-INF\ directory.

5. Save changes to the web.xml file.

6. Launch your client/node.

You can decode your hallmark by doing such a request: http://localhost:7874/nxt?requestType=decodeHallmark&hallmark=HEX_STRING. The hallmark does NOT contain your private key (only public one and signature).

An example to retrieve your hallmark:
http://localhost:7874/nxt?requestType=markHost&secretPhrase=123&host=88.198.210.245&weight=1000&date=2013-12-13

An example to check a hallmark:
http://localhost:7874/nxt?requestType=decodeHallmark&allmark=f2593579978536d185336032190675342356009a3e1b578a7f54e85c14090c0039382e38392e3130332e3235640000008d2d3301a8e38e0db768a7b4db1b83517e23c676b0885c00093ed908a1ac29d00b4c0d540327127c17ce416b03ee800c663764456ce175aa33746d02553ad8b4c0d1221f256271

_____________________________________________________________________

Auth Tokens:
You should generate a different token for each site you are on, unless you have the same exact ID on different sites.

To generate a token for use on a particular site:

1) Get java process and client running, unlock and use your passphrase

2) Click on the key in the upper left.  A popup box comes up asking for a domain.  Just put in your username for the site you want to generate a token for.

3)You will be given a LONG string.  This is your token.  Give it out freely.


To verify a token from another member:

1) Make sure your local client is running

2) Use the values given to you <USERID> and <TOKEN> in the following URL:

3) Surf to: http://127.0.0.1:7874/nxt?requestType=decodeToken&website=<USERID>&token=<TOKEN>

4) Your client will tell you if it checks out OK.  Look for ' "valid":true ' in the response.


_____________________________________________________________________

Graceful Stop of the Java process:
This minimizes chances of data corruption when you want to stop the client

1) Select a local TCP port (I would pick between 10000 and 60000) and a local password to use for stopping the client.  These become the STOP.PORT and STOP.KEY values in the next step.

2) Change your .bat file that starts the client and add the following after "start.jar ":

3) STOP.PORT=10000 STOP.KEY=password

4) Create a second .bat file that is used to stop the client.  It is identical to the commands in the start file, including your addition ins step 3 above, except it also contains the following at the end: " --stop"

5) Just run the second .bat file whenever you need the client to stop.

______________________________________________________


Network ports and NAT/firewalls:
There are three TCP ports in use by the client

TCP port 7874 is the peer2peer port used for comms between peers across the world.  While it is not a requirement to forward this port in the firewall to your client, it does help the network if this is enabled.  If this port is not forwarded to the client host, then the client host will initiate all connections outbound to peers in the network but will never be able to receive initiated connections.  In addition, it should be possible to use multiple clients behind the same NAT to connect out to external peers.  Obviously though, if this is desired, then only 1 of the clients host behind that NAT can be selected to have TCP 7874 forwarded by NAT to it for external inbound connections.

TCP port 7874 is also currently the port used for API request into the client to access different API opertions.  For example, see above for an API request to decode an auth token.

TCP port 7875 is the HTTPS port used to point your web browser at to begin mining.  It is suggested for most users to not forward this port on a NAT firewall unless you really know what you are doing.

TCP port 7876 appears to no longer be in use, at least for the latest versions of the client.  It use to be the API port.

[LiQio]

Very good, thanks for the summary

one question: should someone without open ports (behind closed firewall) to the outside also set this hallmark, or is it just usable for peers (accessible from outside)

one remark: it's not reasonable for someone with changes of the external IP (typical DSL customer, at least where I live) to set the hallmark - at least I understand it that way - and if it's correct, you should emphasize it in your post

[opticalc]

I believe that when all ports are closed, and then you initiate a connection outbound to a host, you still use the hallmark to authenticate yourself, if set.

Good catch on the dynamic IP thing, I put a disclaimer in there.  I do have DSL that changes the IP every time it reboots, or if the DSL ever resyncs.  Mine has been up 6 days though, hopefully wont have to deal with it too often.

I did notice that immed after setting hallmark I got TONS of more active and known peers, and TONS less blacklisted peers.

Looks like hallmarking is good for the network.

[pinarello]

Optical, thank you just what I needed.

my ISP dont allow fixed IP 

[opticalc]

how stable is your connection, and how stable is the power to your modem/router?  Ive elected to just implement the hallmark, and that whenever I see no active peers, that means my IP changed and its time to redo the hallmark.  7 days so far

[pandaisftw]

What would be the danger of hallmarking from your personal IP vs. a VPS?

[opticalc]

supposedly privacy/security issues, but I dont quite get it.  Maybe someone else can explain

[achim]

Also, When I'm hallmarked, I handle more traffic. Do I get better chances at forging a block?

[Come-from-Beyond]

Hallmark contains ur account id and IP, create a strong connection between them. It doesn't prove that owner of the account == owner of the VPS but still...

More traffic means less orphaned blocks but doesn't increase chance to forge.

[opticalc]

Auth Tokens:
You should generate a different token for each site you are on, unless you have the same exact ID on different sites.

To generate a token for use on a particular site:

1) Get java process and client running, unlock and use your passphrase

2) Click on the key in the upper left.  A popup box comes up asking for a domain.  Just put in your username for the site you want to generate a token for.

3)You will be given a LONG string.  This is your token.  Give it out freely.


To verify a token from another member:

1) Make sure your local client is running

2) Use the values given to you <USERID> and <TOKEN> in the following URL:

3) Surf to: http://127.0.0.1:7874/nxt?requestType=decodeToken&website=<USERID>&token=<TOKEN>

4) Your client will tell you if it checks out OK.  Look for ' "valid":true ' in the response.

[opticalc]

Graceful Stop of the Java process:
This minimizes chances of data corruption when you want to stop the client

1) Select a local TCP port (I would pick between 10000 and 60000) and a local password to use for stopping the client.  These become the STOP.PORT and STOP.KEY values in the next step.

2) Change your .bat file that starts the client and add the following after "start.jar ":

3) STOP.PORT=10000 STOP.KEY=password

4) Create a second .bat file that is used to stop the client.  It is identical to the commands in the start file, including your addition ins step 3 above, except it also contains the following at the end: " --stop"

5) Just run the second .bat file whenever you need the client to stop.

[ferment]

Graceful Stop of the Java process:
This minimizes chances of data corruption when you want to stop the client

On mac and linux, I find that using standard linux signals works fine. Here's the start/stop code I use in nxtbase.

Start:

Code: [Select]

$ java -jar start.jar &
$ echo $! > PID

Stop:

Code: [Select]

PID=`cat nxt/PID`
kill $PID
rm PID

If you don't have a PID file, you can use something like this:

Code: [Select]

PID=`ps | grep "start.jar" | grep -v "grep" | awk '{print $1}'`
kill $PID


[opticalc]

Network ports and NAT/firewalls:
There are three TCP ports in use by the client

TCP port 7874 is the peer2peer port used for comms between peers across the world.  While it is not a requirement to forward this port in the firewall to your client, it does help the network if this is enabled.  If this port is not forwarded to the client host, then the client host will initiate all connections outbound to peers in the network but will never be able to receive initiated connections.  In addition, it should be possible to use multiple clients behind the same NAT to connect out to external peers.  Obviously though, if this is desired, then only 1 of the client hosts behind that NAT can be selected to have TCP 7874 forwarded by NAT to it for external inbound connections.

TCP port 7874 is also currently the port used for API request into the client to access different API opertions.  For example, see above for an API request to decode an auth token.

TCP port 7875 is the HTTPS port used to point your web browser at to begin mining.  It is suggested for most users to not forward this port on a NAT firewall unless you really know what you are doing.

TCP port 7876 appears to no longer be in use, at least for the latest versions of the client.  It use to be the API port.