From 47c0876ab3493eff39a81e51ba1b8883ec9056e3 Mon Sep 17 00:00:00 2001 From: zzz Date: Thu, 29 Dec 2022 12:52:48 -0500 Subject: [PATCH] SAM: Add general guidance section Emphasize that i2pd and Java i2p have different defaults --- i2p2www/pages/site/docs/api/samv3.html | 48 +++++++++++++++++++++++--- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/i2p2www/pages/site/docs/api/samv3.html b/i2p2www/pages/site/docs/api/samv3.html index 0b36d389..4c1f3dbd 100644 --- a/i2p2www/pages/site/docs/api/samv3.html +++ b/i2p2www/pages/site/docs/api/samv3.html @@ -1,7 +1,7 @@ {% extends "global/layout.html" %} {% block title %}SAM V3{% endblock %} -{% block lastupdated %}2022-11{% endblock %} -{% block accuratefor %}1.9.0{% endblock %} +{% block lastupdated %}2022-12{% endblock %} +{% block accuratefor %}2.0.0{% endblock %} {% block content %}

SAM is a simple client protocol for interacting with I2P. SAM is the recommended protocol for non-Java applications to connect to the I2P network, @@ -258,6 +258,34 @@ To implement a basic TCP-only, peer-to-peer application, the client must support +

General Guidance for Developers

+

+SAM sessions (or inside I2P, tunnel pools or sets of tunnels) are designed to be long-lived. +Most applications will only need one session, created at startup and closed on exit. +I2P is different from Tor, where circuits may be rapidly created and discarded. +Think carefully and consult with I2P developers before designing your application +to use more than one or two simultaneous sessions, or to rapidly create and discard them. +Most threat models will not require a unique session for every connection. +

+Also, please ensure your application settings +(and guidance to users about router settings, or router defaults if you bundle a router) +will result in your users contributing more resources to the network than they consume. +I2P is a peer-to-peer network, and the network cannot survive if a popular application +drives the network into permanent congestion. +

+The Java I2P and i2pd routers have different defaults for tunnel quantities. +The Java default is 2 and the i2pd default is 5. +For most low- to medium-bandwidth and low- to medium-connection counts, +2 or 3 is sufficient. +Please specify the tunnel quantity in the SESSION CREATE message +to get consistent performance with the Java I2P and i2pd routers. +See below. +

+For more guidance to developers on ensuring your application uses only the resources it needs, please see +our guide to bundling I2P with your application. +

+ +

Version 3 Changes

@@ -624,7 +652,17 @@ $nickname is the choice of the client. No whitespace is allowed.

Additional options given are passed to the I2P session configuration if not interpreted by the SAM bridge (e.g. -outbound.length=0). These options are documented below. +outbound.length=0). +

+The Java I2P and i2pd routers have different defaults for tunnel quantities. +The Java default is 2 and the i2pd default is 5. +For most low- to medium-bandwidth and low- to medium-connection counts, +2 or 3 is sufficient. +Please specify the tunnel quantities in the SESSION CREATE message +to get consistent performance with the Java I2P and i2pd routers, +using the options e.g. inbound.length=3 outbound.length=3. +These and other options are documented in the links below. +

The SAM bridge itself should already be configured with what router @@ -1663,11 +1701,11 @@ their meaning:

Tunnel, I2CP, and Streaming Options

-These options may be passed in as name=value pairs at the end of a +These options may be passed in as name=value pairs in the SAM SESSION CREATE line.

-All sessions may include I2CP options such as tunnel lengths. +All sessions may include I2CP options such as tunnel lengths and quantities. STREAM sessions may include Streaming library options.

See those references for option names and defaults.