La dernière mise à jour de cette page été effectuée en Novembre 2017 et est exacte pour la version 0.9.32 du routeur.

Aperçu

Cette page traite de l’intégration du routeur entier d’I2P dans votre application. Elle ne traite pas de l’écriture d’une application compatible avec I2P (ni intégrée ni externe).

Ne nombreux projets intègrent I2P ou en parlent. C’est très bien si cela est bien fait. Si cela est mal fait, cela pourrait considérablement nuire à notre réseau. Le routeur I2P est complexe et cacher toute cette complexité à vos utilisateurs peut se révéler être un défi.. Cette page aborde de quelques directives générales.

Parlez-nous

Lancez la conversation. Nous sommes ici pour aider. Les applications qui intègrent I2P sont pour nous les occasions les plus prometteuses et les passionnantes d’agrandir le réseau et d’améliorer l’anonymat pour tous.

Choisir judicieusement votre routeur

Si votre application est en Java ou en Scala, le choix est facile. Utiliser le routeur en Java. Si elle est en C/C ++, nous recommandons i2pd. Le développement d’i2pcpp s’est arrêté. Pour des applis écrites dans d’autres langages, il est préférable d’utiliser SAM ou BOB ou SOCKS et d’intégrer le routeur en Java comme processus séparé. Une partie de ce qui suit ne s’applique qu’au routeur en Java.

Autorisation d’exploitation

Assurez-vous de répondre aux exigences de licence des logiciels que vous intégrez.

Verify default configuration

Une configuration par défaut correcte est essentielle. La plupart des utilisateurs ne changeront pas les valeurs par défaut. Les valeurs par défaut pour votre application pourraient être différentes des valeurs par défaut du routeur que vous intégrez. Écrasez si nécessaire les valeurs par défaut du routeur.

Some important defaults to review: Max bandwidth, tunnel quantity and length, max participating tunnels. A lot of this depends on the expected bandwidth and usage patterns of your app.

Configure enough bandwidth and tunnels to allow your users to contribute to the network. Consider disabling external I2CP, as you probably don't need it and it would conflict with any other running I2P instance. Also look at the configs for disabling killing of the JVM on exit, for example.

Participating Traffic Considerations

It may be tempting for you to disable participating traffic. There's several ways to do this (hidden mode, setting max tunnels to 0, setting shared bandwidth below 12 KBytes/sec). Without participating traffic, you don't have to worry about graceful shutdown, your users don't see bandwidth usage not generated by them, etc. However, there's lots of reasons why you should allow participating tunnels.

First of all, the router doesn't work that well if it doesn't have a chance to "integrate" with the network, which is helped tremendously by others building tunnels through you.

Secondly, over 90% of the routers in the current network allow participating traffic. It's the default in the Java router. If your application doesn't route for others and it gets really popular, then it's a leech on the network, and it upsets the balance we have now. If it gets really big, then we become Tor, and spend our time begging for people to enable relaying.

Thirdly, participating traffic is cover traffic that helps your users' anonymity.

We strongly discourage you from disabling participating traffic by default. If you do this and your application gets hugely popular, it could break the network.

Persistance

Vous devez enregistrer les données du routeur (netdb, configuration, etc.) entre les exécutions du routeur. I2P ne fonctionne pas bien si vous devez réensemencer à chaque démarrage. C’est une charge énorme sur nos serveurs de réensemencement et n’est pas non plus très bon pour l’anonymat. Même si vous groupez les infos de routeur, I2P a besoin de données de profil enregistrées pour des performances optimales.

Configurability

Donnez à vos utilisateurs une façon de changer la configuration des paramètres importants. Nous comprenons que vous voudrez probablement cacher la majorité de la complexité d’I2P, mais il est important de présenter quelques paramètres de base. En plus des valeurs par défaut dessus, quelques paramètres réseau tels qu’UPnP, IP/port pourraient être utiles.

Floodfill Considerations

Above a certain bandwidth setting, and meeting other health criteria, your router will become floodfill, which may cause a large increase in connections and memory usage (at least with the Java router). Think about whether that's OK. You can disable floodfill, but then your fastest users aren't contributing what they could. It also depends on the typical uptime for your application.

Réensemencement

Decide if you are bundling router infos or using our reseed hosts. The Java reseed host list is in the source code, so if you keep your source up to date, the host list will be also. Be aware of possible blocking by hostile governments.

Reduce Network Resource Usage

Consider setting your application tunnels to delay-open, reduce-on-idle and/or close-on-idle. This is straightforward if using i2ptunnel but you'll have to implement some of it yourself if using I2CP directly. See i2psnark for code that reduces tunnel count and then closes the tunnel, even in the presence of some background DHT activity.

Updatability

Have an auto-update feature if at all possible, or at least auto-notification of a new version. Our biggest fear is a huge number of routers out there that can't be updated. We have about 6-8 releases a year of the Java router, and it's critical to the health of the network that the users keep up. We usually have over 80% of the network on the latest release within 6 weeks after the release, and we'd like to keep it that way. You don't need to worry about disabling the router's built-in auto-update function, as that code is in the router console, which you presumably are not bundling.

Rollout

Have a gradual rollout plan. Don't overwhelm the network all at once. We currently have approximately 25K unique users per day and 40K uniques per month. We are probably able to handle growth of 2-3X per year without too much issue. If you anticipate a faster rampup than that, OR the bandwidth distribution (or uptime distribution, or any other significant characteristic) of your userbase is significantly different from our current userbase, we really need to have a discussion. The bigger your growth plans, the more important everthing else in this checklist is.

Design for and Encourage Long Uptimes

Tell your users that I2P works best if it keeps running. It may be several minutes after startup before it works well, and even more after first install. If your average uptime is less than an hour, I2P is probably the wrong solution.

Show Status

Provide some indication to the user that the application tunnels are ready. Encourage patience.

Fermeture respectueuse

If possible, delay the shutdown until your participating tunnels expire. Don't let your users break tunnels easily, or at least ask them to confirm.

Education and Donation

It would be nice if you give your users links to learn more about I2P and to donate.

External Router Option

Depending on your user base and application, it may be helpful to provide an option or a separate package to use an external router.

Use of other Common Services

Si vous prévoyez utiliser ou vous relier à d’autres services I2P habituels (fils d’actualité, abonnements hosts.txt, traqueurs, mandataires sortants, etc.), assurez-vous de ne pas les surcharger et parlez aux personnes qui les exploitent pour vous assurer que tout va bien.

Time / NTP Issues

I2P includes an SNTP client. I2P requires correct time to operate. It will compensate for a skewed system clock but this may delay startup. You may disable I2P's SNTP queries, but this isn't advised unless your application makes sure the system clock is correct.

Choose What and How you Bundle

Il vous faudra au minimum i2p.jar, router.jar, streaming.jar mstreaming.jar. Vous pouvez omettre les deux jars de diffusion (streaming) pour une appli de datagrammes seulement. Certaines applis pourraient avoir d’autres besoins, p. ex. i2ptunnel.jar ou addressbook.jar. Ne pas oublier jbigi.jar ou un sous-ensemble de ce dernier pour les plateformes que vous prenez en charge afin d’accélérer grandement la cryptographie. Nous les compilons actuellement pour Java 7 à partir de 0.9.24. La source est essentiellement compatible avec Java 6 si vous souhaitez compiler vous-même, mais nous pourrions commencer à utiliser des fonctions Java 7 n’importe quand, sans avis. Si vous compilez des paquets Debian ou Ubuntu, vous devriez utiliser le paquet I2P de notre PPA au lieu de l’intégrer. Vous n’avez par exemple vraisemblablement pas besoin de susimail, de susidns, de la console du routeur ni d’i2psnark.

Les fichiers suivants devraient être inclus dans le répertoire d’installation d’I2P en indiquant la propriété « i2p.dir.base ». Ne pas oublier les certificats/réensemencement et certificats/SSL exigés pour le réensemencement et blocklist.txt pour la validation IP. Le répertoire geoip est facultatif, mais recommandé afin que le routeur puisse prendre des décisions d’après la position géographique. Le fichier hosts.txt pourrait être utile. Vous pouvez le modifier pour inclure n’importe quel hôte que votre application utilise. Vous pouvez ajouter un fichier router.config répertoire de base pour supplanter les valeurs par défaut initiales.

License requirements may require you to include the LICENSES.txt file and the licenses directory.

  • You may also wish to bundle a hosts.txt file.
  • Assurez-vous d’indiquer un bootclasspath Java 7 si vous compilez avec Java 8.

Considérations pour Android

Notre appli routeur pour Android peut être partagée par plusieurs clients. Si elle n’est pas installée, une invite apparaîtra à l’utilisateur lors du démarrage d’une appli client.

Des développeurs ont exprimé des inquiétudes quant au confort d’utilisation, et ils souhaitent intégrer le routeur dans leur appli. Une bibliothèque de services du routeur est prévue pour Android, ce qui pourrait faciliter l’intégration. Plus de renseignements sont nécessaires.

Pour de l’assistance, veuillez nous contacter.

Jars Maven

We have a limited number of our jars on Maven Central. There are numerous trac tickets for us to address that will improve and expand the released jars on Maven Central.

Pour de l’assistance, veuillez nous contacter.

Datagram (DHT) considerations

If your application is using I2P datagrams, e.g. for a DHT, there's lots of advanced options available to reduce overhead and increase reliability. This may take some time and experimentation to get working well. Be aware of size/reliability tradeoffs. Talk to us for help. It is possible - and recommended - to use Datagrams and Streaming on the same Destination. Don't create separate Destinations for this. Don't try to store your unrelated data in the existing network DHTs (iMule, bote, bittorrent, and router). Build your own. If you are hardcoding seed nodes, we recommend that you have several.

Comarketing

Travaillons ensemble. N’attendez pas que ce soit fini. Donnez-nous votre nom d’utilisateur Twitter et commencez à gazouiller à ce propos. Nous vous rendrons la pareille.

Logiciels malveillants

Veuillez ne pas utiliser I2P pour faire le mal. Cela pourrait considérablement nuire à notre réseau et à notre réputation.

Joignez-vous à nous

Cela peut paraître évident, mais joignez-vous à la communauté. Laissez tourner I2P jour et nuit. Créez un site eep au sujet de votre projet. Visitez notre IRC #i2p-dev. Publiez dans les forums. Passez le mot. Nous pouvons vous aider à obtenir des utilisateurs, des testeurs, des traducteurs ou même des codeurs.

Application Examples

You may wish to install and play with the I2P Android app, and look at its code, for an example of an application that bundles the router. See what we expose to the user and what we hide. Look at the state machine we use to start and stop the router. Other examples are: Vuze, the Nightweb Android app, iMule, TAILS, iCloak, and Monero.

Code Example

None of the above actually tells you how to write your code to bundle the Java router, so following is a brief example.

import java.util.Properties;
import net.i2p.router.Router;

	Properties p = new Properties();
        // add your configuration settings, directories, etc.
        // where to find the I2P installation files
	p.addProperty("i2p.dir.base", baseDir);
        // where to find the I2P data files
	p.addProperty("i2p.dir.config", configDir);
        // bandwidth limits in K bytes per second
	p.addProperty("i2np.inboundKBytesPerSecond", "50");
	p.addProperty("i2np.outboundKBytesPerSecond", "50");
	p.addProperty("router.sharePercentage", "80");
	p.addProperty("foo", "bar");
	Router r = new Router(p);
        // don't call exit() when the router stops
	r.setKillVMOnEnd(false);
	r.runRouter();

	...

	r.shutdownGracefully();
	// will shutdown in 11 minutes or less

This code is for the case where your application starts the router, as in our Android app. You could also have the router start the application via the clients.config and i2ptunnel.config files, together with Jetty webapps, as is done in our Java packages. As always, state management is the difficult part.

See also: the Router javadocs.