概観

このページでは、ご自分のアプリケーションにI2Pルーターのバイナリ全体をバンドルすることについて記載しています。 I2Pと動作するアプリケーションの作成についてではありません（バンドルにせよ、外部にせよ）。 However, many of the guidelines may be useful even if not bundling a router.

多くのプロジェクトはI2Pをバンドルしているか、バンドルについて話し合っています。正しくやれば素晴らしいことです。 間違ってやってしまうと、ネットワーク上に実害を及ぼしうります。 I2Pルーターは複雑で、あなたのユーザーからその複雑性をすべて隠すことは難しいことでしょう。 このページでは一般的なガイドラインをいくつかご紹介します。

Most of these guidelines apply equally to Java I2P or i2pd. However, some guidelines are specific to Java I2P and are noted below.

私たちに連絡

対話を始めましょう。助けになるためにここにいます。I2Pを埋め込んだアプリケーションは、私たちがネットワークを成長させ 皆の匿名性を向上させるうえで非常に有望でワクワクする機会です。

ルーターを賢く選ぶ

アプリケーションがJavaまたはScalaの場合は、簡単な選択です。Javaルーターを使いましょう。 C/C++の場合は、i2pdをお勧めします。i2pcppの開発は停止しました。 他の言語のアプリでは、SAMかBOBまたはSOCKSを使用し、別のプロセスとしてJavaルーターをバンドルすることがベストでしょう。 以下のいくつかはJavaルーターにのみ適用されます。

ライセンス

バンドルするソフトウェアのライセンス用件を満たしているか確認してください。

Configuration

デフォルト設定の確認

適切なデフォルト設定は重要です。ほとんどのユーザーはデフォルトから変更しません。 アプリケーションのデフォルトはバンドルするルーターのデフォルトとは異なっている必要があるかもしれません。 必要に応じてルーターのデフォルト設定を上書きしてください。

確認すべき重要なデフォルトがいくつかあります：最大帯域幅、トンネルの数量と長さ、最大参加トンネル数です。 この多くがアプリの予想帯域幅と使用パターンに依存します。

ネットワークにユーザーが貢献できるのに十分な帯域幅とトンネルを設定してください。 おそらく必要としておらず、また他の起動中のI2Pインスタンスと競合する場合があるので、外部I2CPを無効化することを検討してください。 また、例えば終了時にJVMをキルすることを無効化する設定を見てください。

参加トラフィックの考慮

参加トラフィックを無効化したくなるかもしれません。 これにはいくつかの方法があります（秘匿モード、最大トンネル数を0に設定、共有帯域幅を12KB/s以下に設定）。 参加トラフィックがなければ、正常なシャットダウンについて心配する必要はありません。 ユーザーが、自分以外によって生み出された帯域幅の使用を見ること等もありません。 しかし、トンネルへの参加を許可しなければならない理由はたくさんあります。

まず第一に、ネットワークに「統合」する機会がなければ、ルーターはうまく動きませんし これはあなたを通じて他のユーザーがトンネルを構築することで大きく助けられます。

第二に、現在のネットワークのルーターの90% 以上が参加トラフィックを許可しています。 Javaルーターではデフォルトです。 もしあなたのアプリケーションが他のユーザーのためにルートせず、アプリが実際に実際に人気になってしまったら それはネットワーク上のヒルですし、現在のバランスを崩してしまいます。 もしこの問題が大きくなれば、私たちはTorになって、人々がリレーを有効にするよう懇願するのに時間を割くことになるでしょう。

第三に、参加トラフィックとは、ユーザーの匿名性を助ける隠しトラフィックです。

デフォルトで参加トラフィックを無効にすることには強く反対します。 これをしながら、あなたのアプリケーションが大いに普及することとなれば、ネットワークを破壊しうります。

持続性

You must save the router's data (netdb, configuration, etc.) between runs of the router. I2P does not work well if you must reseed each startup, and that's a huge load on our reseed servers, and not very good for anonymity either. Even if you bundle router infos, I2P needs saved profile data for best performance. Without persistence, your users will have a poor startup experience.

There are two possibilities if you cannot provide persistence. Either of these eliminates your project's load on our reseed servers and will significantly improve startup time.

1) Set up your own project reseed server(s) that serve much more than the usual number of router infos in the reseed, say, several hundred. Configure the router to use only your servers.

2) Bundle one to two thousand router infos in your installer.

Also, delay or stagger your tunnel startup, to give the router a chance to integrate before building a lot of tunnels.

Configurability

Give your users a way to change the configuration of the important settings. We understand that you will probably want to hide most of I2P's complexity, but it's important to show some basic settings. In addition to the defaults above, some network settings such as UPnP, IP/port may be helpful.

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.

再シード

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.

Use Shared Clients

Java I2P i2ptunnel supports shared clients, where clients may be configured to use a single pool. If you require multiple clients, and if consistent with your security goals, configure the clients to be shared.

Limit Tunnel Quantity

Specify tunnel quantity explicitly with the options inbound.quantity and outbound.quantity. The default in Java I2P is 2; the default in i2pd is higher. Specify in the SESSION CREATE line using SAM to get consistent settings with both routers. Two each in/out is sufficient for most low-to-medium bandwidth and low-to-medium fanout applications. Servers and high-fanout P2P applications may need more. See this forum post for guidance on calculating requirements for high-traffic servers and applications.

Specify SAM SIGNATURE_TYPE

SAM defaults to DSA_SHA1 for destinations, which is not what you want. Ed25519 (type 7) is the correct selection. Add SIGNATURE_TYPE=7 to the DEST GENERATE command, or to the SESSION CREATE command for DESTINATION=TRANSIENT.

Limit SAM Sessions

Most applications will only need one SAM session. SAM provides the ability to quickly overwhelm the local router, or even the broader network, if a large number of sessions are created. If multiple sub-services can use a single session, set them up with a PRIMARY session and SUBSESSIONS (not currently supported on i2pd). A reasonable limit to sessions is 3 or 4 total, or maybe up to 10 for rare situations. If you do have multiple sessions, be sure to specify a low tunnel quantity for each, see above.

In almost no situation should you require a unique session per-connection. Without careful design, this could quickly DDoS the network. Carefully consider if your security goals require unique sessions. Please consult with the Java I2P or i2pd developers before implementing per-connection sessions.

Reduce Network Resource Usage

Note that these options are not currently supported on i2pd. These options are supported via I2CP and SAM (except delay-open, which is via i2ptunnel only). See the I2CP documentation (and, for delay-open, the i2ptunnel configuration documentation) for details.

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.

Life Cycle

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.

User Interface

Show Status

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

Graceful Shutdown

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.

Other Topics

Use of other Common Services

If you plan to use or link to other common I2P services (news feeds, hosts.txt subscriptions, trackers, outproxies, etc.), make sure you aren't overloading them, and talk to the people who are running them to make sure it's ok.

Time / NTP Issues

Note: This section refers to Java I2P. i2pd does not include an SNTP client.

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

Note: This section refers to Java I2P only.

At a minimum you will need i2p.jar, router.jar, streaming.jar, and mstreaming.jar. You may omit the two streaming jars for a datagram-only app. Some apps may need more, e.g. i2ptunnel.jar or addressbook.jar. Don't forget jbigi.jar, or a subset of it for the platforms you support, to make the crypto much faster. Java 7 or higher is required to build. If you're building Debian / Ubuntu packages, you should require the I2P package from our PPA instead of bundling it. You almost certainly do not need susimail, susidns, the router console, and i2psnark, for example.

The following files should be included in the I2P installation directory, specified with the "i2p.dir.base" property. Don't forget the certificates/ directory, which is required for reseeding, and blocklist.txt for IP validation. The geoip directory is optional, but recommended so the router can make decisions based on location. If including geoip, be sure to put the file GeoLite2-Country.mmdb in that directory (gunzip it from installer/resources/GeoLite2-Country.mmdb.gz). The hosts.txt file may be necessary, you may modify it to include any hosts your application uses. You may add a router.config file to the base directory to override initial defaults. Review and edit or remove the clients.config and i2ptunnel.config files.

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.
• Be sure to specify a bootclasspath if you are compiling Java I2P for your release, rather than taking our binaries.

Android considerations

Note: This section refers to Java I2P only.

Our Android router app may be shared by multiple clients. If it is not installed, the user will be prompted when he starts a client app.

Some developers have expressed concern that this is a poor user experience, and they wish to embed the router in their app. We do have an Android router service library on our roadmap, which could make embedding easier. More information needed.

If you require assistance, please contact us.

Maven jars

Note: This section refers to Java I2P only.

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.

If you require assistance, please contact us.

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.

Outproxies

I2P outproxies to the clearnet are a limited resource. Use outproxies only for normal user-initiated web browsing or other limited traffic. For any other usage, consult with and get approval from the outproxy operator.

Comarketing

Let's work together. Don't wait until it's done. Give us your Twitter handle and start tweeting about it, we will return the favor.

Malware

Please don't use I2P for evil. It could cause great harm both to our network and our reputation.

Join Us

This may be obvious, but join the community. Run I2P 24/7. Start an I2P Site about your project. Hang out in IRC #i2p-dev. Post on the forums. Spread the word. We can help get you users, testers, translators, or even coders.

Examples

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

Note: This section refers to Java I2P only.

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.