The MuWire user manual (an overview and introduction)

[lgillis]

Editorial: This forum does not support GeSHi, the text formatting is accordingly simple.
The latest version of the manual as an HTML and PDF document via sharefile.i2p:
Link: The MuWire user manual.html, 2024-09-05, text/html, 58.47 KB
Link: The MuWire user manual.pdf, application/pdf, 159.52 KB

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
THE MUWIRE USER MANUAL
An overview and introduction
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


Table of Contents
─────────────────

1. The MuWire user manual
.. 1. Download
.. 2. Installation
.. 3. Running MuWire
.. 4. Features
..... 1. Search by keyword or file hash
..... 2. Comments and Collections
..... 3. File Feeds
..... 4. Messages and Chat
..... 5. File Certificates
..... 6. Web of Trust
.. 5. About MuWire
..... 1. Example use case
..... 2. Behind the scenes
..... 3. Motivation
.. 6. Nicknames
..... 1. Managing your identity
..... 2. Moving to another computer
..... 3. Creating a new identity
........ 1. Multiple identities
.. 7. MuWire Communications
..... 1. Messages
........ 1. Attachments
..... 2. Chat
........ 1. Connecting To Someone Else’s Server
........ 2. Running Your Own Server
..... 3. Private Messages
..... 4. Blocking And Banning Users
.. 8. File Collections
..... 1. Creating collections
..... 2. Deleting collections
..... 3. Searching for collections
..... 4. Downloading collections
..... 5. A word of warning
.. 9. File Feeds
..... 1. Personal feed options
..... 2. Note about unpublishing
.. 10. Shared File Certificates
..... 1. Why certificates are useful
..... 2. Under the hood
.. 11. Search Phrases
.. 12. Sidecar files
..... 1. Requirements
..... 2. Notes about editing comments manually
..... 3. Deleting comments
..... 4. Note about symlinks
.. 13. Trust
..... 1. Why trust other users
..... 2. Distrusting users
..... 3. Deciding whom to trust
.. 14. Miscellaneous
..... 1. MuWire and I2Pd
..... 2. Drag and drop
..... 3. Advertise the software MuWire
..... 4. How to set the language of the GUI
..... 5. Final words
..... 6. Editorial


1 The MuWire user manual
════════════════════════

Easy anonymous file sharing using `I2P' technology.

`MuWire' is an anonymous file-sharing program. You can share, search
and download files of any type. For more information, see [About
MuWire].

`MuWire' is completely free and open source. There are no bundled ads
or offers of any kind.

`MuWire' works on any platform Java works on, including Windows,
MacOS, Linux, Rapsberry Pi.

You can find technical documentation in the doc (github.com) folder.
Also check out the Wiki (github.com) for various other documentation:

• <https://github.com/zlatinb/muwire> clearnet repository.
• <https://git.idk.i2p/zlatinb/muwire> in-I2P access for the `I2P'
GitLab repository.
• <https://i2pgit.org/zlatinb/muwire> clearnet access to the `I2P'
GitLab repository.
*Dokumentation und Wiki:*
• <https://github.com/zlatinb/muwire/wiki>
• <https://git.idk.i2p/zlatinb/muwire/-/wikis/home>
• <https://github.com/zlatinb/muwire/tree/master/doc>


[About MuWire] See section 1.5

1.1 Download
────────────

The current stable release is available for download at:

• <https://github.com/zlatinb/muwire>
• [tracker2.postman.i2p] (uploader: zlatin)

And of course within the `MuWire' network, whereby current versions
can be downloaded automatically.


[tracker2.postman.i2p]
<http://tracker2.postman.i2p/?view=Main& ... =0&lang=-1>


1.2 Installation
────────────────

The following information refers to the currently available beta
version up to and including 0.8.14-beta2 from August 30, 2022.

In an environment like this, you should only use the latest I2P
versions for your own protection. MuWire's internal I2P-Router is
considered obsolete, you should no longer use it. Instead, install the
latest version of I2Pd or Java-I2P and run MuWire over it.

/Please note: Only use the versions from the official manufacturers./

The addresses specified by the external router are used for this. An
example can be found below [MuWire and I2Pd].


[MuWire and I2Pd] See section 1.14.1


1.3 Running MuWire
──────────────────

The first time you start `MuWire' it takes a few minutes to load.

The first time you run `MuWire' it will ask you to choose a nickname.
That nickname is combined with a cryptographically strong `I2P'
address and forms your unique identity on `MuWire'. For more info see
`MuWire' [Nicknames].


[Nicknames] See section 1.6


1.4 Features
────────────

1.4.1 Search by keyword or file hash
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

You can search by keywords or by file hash. All keywords have to match
for a result to be returned. If want to share or find a specific file
you can use the hash to make sure it is the right one. You can also
use [Search Phrases].


[Search Phrases] See section 1.11


1.4.2 Comments and Collections
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

You can add comments to your shared files with `MuWire' or by using
[Sidecar Files].
When someone searches for a keyword that is present in a comment, they
will see a search result for that file. You can group several files
together into a Collection.


[Sidecar Files] See section 1.12


1.4.3 File Feeds
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

You can publish your shared files to your personal feed, and subscribe
to the feeds of other users. This is similar to following someone on a
social network. For more info see [File Feeds].


[File Feeds] See section 1.9


1.4.4 Messages and Chat
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

You can communicate with other `MuWire' users anonymously. For more
information, see `MuWire' Communications. You can communicate
anonymously with other users via the integrated [chat] system and
messaging (EMail)


[chat] See section 1.7.2


1.4.5 File Certificates
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

You can issue a certificate for a file you share to prove to others
that you have the file. For more info see File Certificates.


1.4.6 Web of Trust
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

You can choose to trust or distrust other `MuWire' users, and see who
they trust and distrust in turn. For more information see [Trust] In
`MuWire'.


[Trust] See section 1.13


1.5 About MuWire
────────────────

`MuWire' is a file publishing and networking tool that protects the
identity of its users by using `I2P' technology. Anyone with a desktop
computer and an internet connection can create a unique anonymous
online persona and publish information of any kind without fear of
censorship or persecution.

Users can then use their `MuWire' identities to publish files, search
for files published by others, subscribe to each other’s publications
and communicate through chat and messaging. Furthermore, users can
establish trust-based relationship with each other where they assign a
“trust level” to their contacts.


1.5.1 Example use case
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

An example use case is that of Alice, a whistle-blower that wishes to
remain anonymous in order to publish sensitive material on an ongoing
basis. She creates a `MuWire' identity (which cannot in any way be
linked to her real-world identity) and uses it to distribute
information. Alice adds the files containing the sensitive material to
her `MuWire' library and leaves `MuWire' running.

Bob is a journalist who does not know anything about Alice, but is
interested in the type of material she publishes. Furthermore, Bob
doesn’t want Alice to know his real-world identity either. He creates
a `MuWire' identity and uses `MuWire' to search for relevant keywords.
Alice’s `MuWire' node receives those queries and responds with results
automatically. Bob then downloads the material from Alice’s `MuWire'
node and verifies that it is genuine and of interest to him. Alice
publishes regularly, so Bob subscribes to her publication feed and his
`MuWire' node fetches automatically everything that Alice has made
public. `MuWire' also offers mailbox messaging and chat functionality,
so Bob can ask Alice for specific material and even have a real-time
chat with her.

The relationship between Alice and Bob is completely anonymous and
neither party can learn more about the other without consent.


1.5.2 Behind the scenes
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

`MuWire' uses the `I2P' network which is known to work even during the
strictest internet clampdowns in countries like China and Iran. The
technology provides protection against Deep Packet Inspection
firewalls and other tools used by state surveillance. From an outside
observer the traffic that `MuWire / I2P' generates is
indistinguishable from random static.


1.5.3 Motivation
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

My motivation for creating `MuWire' is to enable every human being to
share information without fear. `MuWire' is just a tool, use it for
good!


1.6 Nicknames
─────────────

Every `MuWire' user has a nickname. The nickname is created by
combining their chosen name with their unique cryptographic `I2P'
address. The nickname has two forms - short and full. The short form
is easier to read, and it looks like:
┌────
│ zlatinb@3k2gijdfdcuczkfypfddj4qsnnf744mj
└────

The full form can be used to find them on the `MuWire' network. For
example, you can use the full form to browse the files they are
sharing. To do that, copy-paste the full nickname into the search
field and press Enter.

Full nicknames are also used to connect to the [Chat] and when logging
in to websites based on the `MuCats' code.

The developer's full nickname is used here as an example:

\begin{verbatim}
AQAHemxhdGluYiN~3G-hPoBfJ04mhcC52lC6TYSwWxH-WNWno9Y35JS-WrXlnP
sodZtwy96ttEaiKTg-hkRqMsaYKpWar1FwayR6qlo0pZCo5pQOLfR7GIM3~wde
0JIBEp8BUpgzF1-QXLhuRG1t7tBbenW2tSgp5jQH61RI-c9flyUlOvf6nrhQMZ
3aoviZ4aZW23Fx-ajYQBDk7PIxuyn8qYNwWy3kWOhGan05c54NnumS3XCzQWFD
DPlADmco1WROeY9qrwwtmLM8lzDCEtJQXJlk~K5yLbyB63hmAeTK7J4iS6f9nn
Wv7TbB5r-Z3kC6D9TLYrQbu3h4AAxrqso45P8yHQtKUA4QJicS-6NJoBOnlCCU
887wx2k9YSxxwNydlIxb1mZsX65Ke4uY0HDFokZHTzUcxvfLB6G~5JkSPDCyZz
~2fREgW2-VXu7gokEdEugkuZRrsiQzyfAOOkv53ti5MzTbMOXinBskSb1vZyN2
-XcZNaDJvEqUNj~qpfhe-ov2F7FuwQUABAAHAAAfqq-MneIqWBQY92-sy9Z0s~
iQsq6lUFa~sYMdY-5o-94fF8a140dm-emF3rO8vuidUIPNaS-37Rl05mAKUCcB
\end{verbatim}

/Please note: All MuWire addresses consist of only one line without
line breaks. To use these examples, line breaks must be removed./


[Chat] See section 1.7.2

1.6.1 Managing your identity
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

The cryptographic part of your `MuWire' identity is stored in a file
called `key.dat' in the `MuWire' settings directory. That directory is
on:

Windows
`c:\Users\<username>\AppData\Roaming\MuWire\'
Mac
`/Users/<username>/Library/Application Support/MuWire'
Linux
`"$HOME"/.MuWire' for older versions or in accordance with the
newer standard `"$HOME"/.config/MuWire'

It is a good idea to backup that file to a safe place. If that file
gets lost, your identity cannot be recovered. Do not give that file to
anyone else or they will be able to impersonate you.

The human-readable part of your identity (the nickname you choose) is
stored in a file called `MuWire.properties'. That file is in text
format and you can edit it with any editor. You can change your
nickname and keep the cryptographic identity but that is not
recommended because it will confuse others users.


1.6.2 Moving to another computer
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

If you want to move `MuWire' to another computer and keep your
identity, you should ideally copy everything from the settings
directory to the new machine. If you can’t, copy at least `key.dat' so
that your identity doesn’t get lost.

Only one `MuWire' instance can run with a given identity at any time.
You can’t have the same identity running on two computers
simultaneously, if you try to do so `MuWire' will have trouble
connecting to the network, searching for files, and will in general
perform poorly.


1.6.3 Creating a new identity
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

To create a new identity stop `MuWire', delete `key.dat' and start
`MuWire' again.


1.6.3.1 Multiple identities
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

If for whatever reason you want to have multiple identities, you need
to create them manually and manage the key.dat files yourself. To
change your identity, stop `MuWire', replace key.dat with the one for
the new identity, and start `MuWire'.


1.7 MuWire Communications
─────────────────────────

`MuWire' has two types of communication abilities - messages and
real-time chat.


1.7.1 Messages
╌╌╌╌╌╌╌╌╌╌╌╌╌╌

You can send direct messages to other `MuWire' users on your contact
list or those returning search results to you. If the `Message button'
is enabled when you select a sender of a result means that user
accepts messages.

If the user is online they will receive your message almost
immediately, otherwise it will stay in your outbox and `MuWire' will
try to send it again automatically.


1.7.1.1 Attachments
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

You can attach files and collections you are sharing with `MuWire' to
messages, no matter how big the files or collections are. (That is
because `MuWire' only sends a “hash” of the files.)


1.7.2 Chat
╌╌╌╌╌╌╌╌╌╌

You can chat anonymously with other `MuWire' users through the
`MuWire' chat system. To do so, you need to either connect to someone
else’s chat server or run a chat server yourself and wait for someone
to connect to you.


1.7.2.1 Connecting To Someone Else’s Server
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

You can see from the search results who is running a `MuWire' server.
If the checkbox in the “Chat” column is checked, you can press the
“Chat” button and `MuWire' will connect to their server. Otherwise,
you can connect to their server if you know their address by pressing
the “Connect To Remote server” button in the “Chat” tab. For example,
I’m (zlatinb) running a chat server at the following address (by the
way, this is the same address as already specified above under
[Nicknames]):

\begin{verbatim}
AQAHemxhdGluYiN~3G-hPoBfJ04mhcC52lC6TYSwWxH-WNWno9Y35JS-WrXlnP
sodZtwy96ttEaiKTg-hkRqMsaYKpWar1FwayR6qlo0pZCo5pQOLfR7GIM3~wde
0JIBEp8BUpgzF1-QXLhuRG1t7tBbenW2tSgp5jQH61RI-c9flyUlOvf6nrhQMZ
3aoviZ4aZW23Fx-ajYQBDk7PIxuyn8qYNwWy3kWOhGan05c54NnumS3XCzQWFD
DPlADmco1WROeY9qrwwtmLM8lzDCEtJQXJlk~K5yLbyB63hmAeTK7J4iS6f9nn
Wv7TbB5r-Z3kC6D9TLYrQbu3h4AAxrqso45P8yHQtKUA4QJicS-6NJoBOnlCCU
887wx2k9YSxxwNydlIxb1mZsX65Ke4uY0HDFokZHTzUcxvfLB6G~5JkSPDCyZz
~2fREgW2-VXu7gokEdEugkuZRrsiQzyfAOOkv53ti5MzTbMOXinBskSb1vZyN2
-XcZNaDJvEqUNj~qpfhe-ov2F7FuwQUABAAHAAAfqq-MneIqWBQY92-sy9Z0s~
iQsq6lUFa~sYMdY-5o-94fF8a140dm-emF3rO8vuidUIPNaS-37Rl05mAKUCcB
\end{verbatim}

/Please note: All MuWire addresses consist of only one line without
line breaks. To use these examples, line breaks must be removed./

Once you connect, you will be greeted with a message “Welcome to my
chat server. Type `/HELP' for list of available commands”. You can
type `/HELP' in the input field and the server will print the commands
it supports.

/Note: No distinction is made between upper and lower case, the
`/HELP' and `/help' commands are identical./

To start chatting, you need to join a room. To see what rooms exist on
the server, type `/LIST'. To join a room or create one, type `/JOIN
<room name>'. For example, on my server there is a room called
“#muwire”. To join that room, type `/JOIN #muwire'. Once you’re in the
room, anything you say will be seen by everyone in the room.


[Nicknames] See section 1.6


1.7.2.2 Running Your Own Server
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

To run your own server, click on the “Chat” tab and press the “Start
Chat Server” button. This will open the “Console” window where you can
control your server. You need to create a room and join it before
someone can start chatting with you.

To see the address of your server, type `/INFO' in the server console.
You can then copy-paste that address and give it to others.


1.7.3 Private Messages
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

To send someone a private message, double-click on their name in the
list of room members to the left, or right-click on their name and
select “Start Private Chat”.

/Please note: Private messages are not encrypted, the server operator
can see them./


1.7.4 Blocking And Banning Users
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

If you are connecting to someone else’s server, you can block other
users from sending you messages by right-clicking on their name and
selecting “Mark Distrusted”. That will not kick the user from the
server, it will only prevent you from seeing anything the user says.

If you are running your own server and mark someone as `DISTRUSTED',
they will be disconnected from your server and will not be able to
connect again.


1.8 File Collections
────────────────────

`MuWire' lets you group several files you’re sharing together into a
single collection. That way you can organize your shared files in a
meaningful way, for example you can have a single collection for all
pictures of a given cat.


1.8.1 Creating collections
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

Go to the “Collections” tab and click on the `Create collection'
button. This will open the collection wizard. Then you need to choose
a name for your collection and optionally add a description.

To add files to your collection they need to first be shared with
`MuWire'. Simply drag the files from the `Library' tab to the
collection wizard. The files do not need to be in the same directory
on your hard drive. The same file can be part of multiple collections.

When you’re finished, click on the `Review' button to see what the
collection will look like to other users. If you’re happy, click
`Save' or you can go back and make changes.


1.8.2 Deleting collections
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

You can delete the collections you have created and that will not
affect the files they contain in any way. They will still be shared
and searchable. If you want to completely remove the files from your
`MuWire' library you need to right-click on them and select `unshare'.

If you try to unshare a file that is part of one or more collections
`MuWire' will warn you that those collections will be deleted.


1.8.3 Searching for collections
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

When you search the `MuWire' network you will receive results that
match the file name and the comment. If the file is part of a
collection, the `View Collections' button will be enabled and you can
see which other files are part of the collection.

If you search for a word that is in the name or description of a
collection, all files that are part of the collection will be returned
as results. You can disable that behavior in the options if you start
getting too many irrelevant results.


1.8.4 Downloading collections
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

You can download individual files from a collection or all at once. If
you download all at once, when the downloads have finished the
collection will be added to your repository.
Browsing collections

If the `Browse collections' button is enabled when you click on a user
name you can see all the collections the given user is sharing.


1.8.5 A word of warning
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

When you create a collection, some directory information gets stored
in it. When you review the collection make sure you’re not leaking too
much information about your directory structure.


1.9 File Feeds
──────────────

With `MuWire' you can publish the files you share to your personal
feed, and subscribe to the feeds of other users. You can configure
each individual feed separately, for example to download all files
published by someone else. This is very similar to following someone
on a social network.

Here is a video demonstrating the Feeds functionality, title: /How to
MuWire: New Feature 'Feeds'/, e.g. [Invidious redirect], [YouTube],
[odysee] … look for it in `MuWire'.


[Invidious redirect]
<https://inv.tux.pizza/channel/UCqFZ4jFz_YwMzN-MVJ4Yb-Q>

[YouTube] <https://www.youtube.com/watch?v=H_p7FknmwVs>

[odysee] <https://odysee.com/@Danrobi:b/Ok-done-w ... -feature:c>

1.9.1 Personal feed options
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

• Enable File Feed - whether to enable or disable your personal feed.
Default is enabled.
• Advertise Feed In Search Results - whether to let other `MuWire'
users know you have a feed. Default is enabled.
• Automatically Publish Shared Files - if enabled, every file you
share or download will be published to your feed right away. Default
is disabled.

Each subscription to someone else’s feed can be configured the
following way:

• Automatically Download - whether to download all new files published
to the feed automatically. Default is false.
• Sequential Download - whether to download each file sequentially.
This makes previewing media files work better. Default is false.
• Items To Keep On Disk - how many of the items published to the feed
to remember across restarts of `MuWire'. If you set this value to
`-1' `MuWire' will remember all items published to the feed. Default
is `1000'.
• Feed Update Frequency - how often to check the feed for new files.
Value is in minutes, default is one hour.


1.9.2 Note about unpublishing
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

You can un-publish a file from your personal feed. Anyone who is
subscribed to your feed and has not yet seen the file you unpublish
will not see it in their list. However, if they have already seen the
file you unpublish, it will not be removed from their list.

If you unshare a file you’ve published it is similar - anyone who is
subscribed to your feed and has already seen the file will continue to
see it. They will not be able to download it though.


1.10 Shared File Certificates
─────────────────────────────

Since `MuWire' version 0.5.8 you can issue certificates for the files
you share. A certificate is a proof that you shared the file, and
anyone on the network can verify that.

/Please note: Once issued a certificate cannot be revoked. Even if you
delete the certificate from your disk, others may have already gotten
it. Do not do this unless you are absolutely sure. The GUI will warn
you about this as well./


1.10.1 Why certificates are useful
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

Certificates help you make a more informed decision whether to
download a file or not. Imagine the following scenario:

• Alice shares a file and issues a certificate for it.
• Bob downloads the file from Alice and imports the certificate Allice
issued.
• Alice then goes offline.
• Charlie comes online and searches for the same file. Bob returns a
search result which says the file has certificates associated with
it.
• Charlie fetches the certificate(s) and verifies that at some point
Alice shared the given file.


1.10.2 Under the hood
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

A certificate is a signed document that contains a timestamp, the name
of the file, the hash of the file and the identity of the person
signing it. If the file has a comment, the comment is stored in the
certificate as well. Because of that, if you change the comment you
need to issue the certificate again.

Certificate files are stored in the subdirectory `filecerts' of the
[settings directory] and follow the naming convention:
`<hash of file>_<issuer>_<timestamp>.mwcert'.

You can view the certificates you have issued or imported with the
`Tools -> Certificates' menu.


[settings directory] See section 1.6.1


1.11 Search Phrases
───────────────────

Since version `0.5.8' `MuWire' supports phrases in search terms. If
you surround several words in quotation marks, you will only see
results that match all those words in that order, either in the file
name or in the comment.

You can also mix phrases with regular keywords, as demonstrated in the
example below. Let’s say you have three shared files:

1. “My Siamese cat videos.avi”
2. “Videos of my Siamese cat.avi”
3. “Cat videos of my Siamese.avi”

Then the following searches will return the following results:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Search term Match no.
───────────────────────────────────
`cat videos' `1, 2, 3'
`"cat videos"' `1, 3'
`"siamese cat videos"' `1'
`siamese "cat videos"' `1, 3'
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


1.12 Sidecar files
──────────────────

Sidecar files are text files that you can use to automatically add
comments to your shared files. The sidecar files themselves are not
shared, but their content is added as a comment to the corresponding
shared file. If the searcher has not disabled searching in comments,
any word present in a comment will trigger search results.


1.12.1 Requirements
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

• The sidecar file is a regular text file, but it will be loaded as
UTF-8 so you can use foreign languages.
• The sidecar file must be present in the same directory as the
corresponding shared file and have the same name but with the added
extension of `.mwcomment'.
• The maximum length of a comment is 32kb. If a sidecar file is longer
than that, it will be ignored.
• You need to share the sidecar file for it to be processed. It will
not appear in your list of shared files, but the corresponding
shared file will be updated to have a comment.


1.12.2 Notes about editing comments manually
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

If you are using sidecar files it’s best not to edit comments manually
through the UI afterwards. If you want to change a comment, change it
in the sidecar file and then re-share the sidecar file.


1.12.3 Deleting comments
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

If you want to completely remove the comment from a shared file you
need to

• Delete the sidecar file
• Delete the comment through the UI

Without both of these steps the comment may re-appear after restart.


1.12.4 Note about symlinks
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

`MuWire' resolves all symlinks, hard and symbolic (symlink). If you
use symlinks for your shared files or sidecar files, the final
resolved path of the sidecar file and the shared file must be the same
in order for the sidecar file to be processed.


1.13 Trust
──────────

In `MuWire' you can choose to trust or distrust other `MuWire' users.
You can subscribe to the contact lists of users you trust and see who
they trust and distrust in turn.


1.13.1 Why trust other users
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

When you mark someone as trusted they get added to your `MuWire'
contact list. You can then easily send them messages, chat with them,
browse the files or collections they’re sharing.

In the `MuWire' options you can choose to allow only trusted
connections. If you enable that option your `MuWire' node will only
connect to the nodes of users that you have marked Trusted. Keep in
mind that you haven’t marked anyone as Trusted you will not be able to
connect to anyone!


1.13.2 Distrusting users
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

If for whatever reason you want to never see anything from a specific
user (like search result or a message) you can mark them as
Distrusted. They will not be able to interact with you in any way.


1.13.3 Deciding whom to trust
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

/Please note: Be careful who you trust in an anonymous network!/

There is no single right answer as to whether you should trust someone
or not. Ideally you should interact with them somehow before making a
decision. Exchange files, messages, or chat with them. People can
change `MuWire' identities easily, and also multiple humans can be
behind the same `MuWire' identity. Be mindful of what information you
give out, and be respectful if others do not want to give you
information about themselves.


1.14 Miscellaneous
──────────────────

1.14.1 MuWire and I2Pd
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

MuWire works with the C++ router I2Pd, but first you need to enable
the `I2P Control Protocol (I2CP)'; that interface is disabled by
default. To check whether `I2CP' is already switched on, `I2Pd’s' web
console is called up under its address [http://127.0.0.1:7070/].

If `I2CP Disabled' is displayed, open the file `i2pd.conf' in the
`I2Pd' configuration directory with a text editor and search for the
section `[i2cp]'. All you have to do is change the following line from
`# enabled = false' to `enabled = true' (also remove the hash `#').
After saving the file, `I2Pd' must be restarted for the changes to
take effect. The web console should now show `I2CP Enabled'.

In 2024, `MuWire' can be configured via the GUI to use an external
router. The configuration is accessed from the Options menu. Select
the I2P tab. The address and port are entered at the bottom under
“External Router I2CP Settings”. Address and port service will listen
on per default:

━━━━━━━━━━━━━━━━━━━━━
`Host' `127.0.0.1'
`Port' `7654'
━━━━━━━━━━━━━━━━━━━━━



The following section describes how to make these settings using a
text editor.

Hi, let’s take care of the `MuWire' connectivity first. Right now it
is definitely not using `I2Pd' but it’s own internal router, and
frankly I’m surprised it works at all because the .zip distribution
does not have the reseed certificates. So here’is what you need to do:

1. Shut down `MuWire',
2. change `"embeddedRouter"' to `"false"' in both `MuWire.properties'
and `i2p.properties' in your [settings directory].
3. If your `I2Pd' router’s `I2CP' (I2P Control Protocol) port is not
default value, edit `i2p.properties' and set the following two
properties to the correct values:
`i2cp.tcp.host=<host of i2pd router, usually 127.0.0.1>'
`i2cp.tcp.port=<the i2cp port of your i2pd router>'
4. Start `MuWire'. If it is correctly using the `I2Pd' router you
should see the `MuWire' tunnel on the `I2Pd' web interface, also it
will launch much faster. Also, `wrapper.log' and `router.config'
will no longer be created at all.


[http://127.0.0.1:7070/] <http://127.0.0.1:7070/>

[settings directory] See section 1.6.1


1.14.2 Drag and drop
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

Next, KDE… I have a KDE virtual machine available so I just tested D&D
- it works from Dolphin, as long as the file doesn’t have brackets [
or ] in the name. Are you dropping on top of the Library tab? You want
to drop directly on top of the `MuWire' window, not on top of the
dialog that appears when you click on “Share”


1.14.3 Advertise the software MuWire
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

Next, advertisement… the last thing I want is to spam postman with my
releases. In the past I used to release a new version every few days
so that was too much. Now I release no more than once a month, so it’s
probably ok to set up torrents there. I’ll set up a torrent for
version 0.8.10 to see if it will be welcome by the users.


1.14.4 How to set the language of the GUI
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

The first question the setup wizard asks is what language you want to
use, but if you want to change it afterwards you need to edit the
`gui.properties' file in your [settings directory] and change the
field `locale=' to the two-letter language code. If you enter a locale
that is not supported MuWire will revert to English. You need to shut
down MuWire before editing the file.

The following languages are currently planned for translation: ar, az,
bg, br, bs, ca, cs, da, de, el, en, es, es_AR, fa, fi, fil, fr, gl,
hi, hr, hu, in, it, iw, ja, ko, mg, mk, nb, nl, nn, om, pl, pt, pt_BR,
ro, ru, sk, sl, sq, sr, sv, tr, uk, ur, vi, zh, zh_TW.


[settings directory] See section 1.6.1


1.14.5 Final words
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

*Enjoy your weekend!*


1.14.6 Editorial
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

The user manual from November 8, 2020, written by zlatinb.
Adapted by Luther H. Gillis (2024).


--
Edit: 2024-09-06 PDF document for download.
Edit: 2024-09-05 update text and html
Edit: http -> https i2pgit.org users please use HTTPS on both clearnet and I2P
Edit: The manual has been inserted as an HTML document for download.

[TNL]

Thanks for posting.

I hope many new users will find their way to MuWire

[lgillis]

Thanks for your reply, TNL!

I have a revised version as a nicely formatted and free-standing HTML file, without JavaScript and no external links. Available here for free:

Link (sharefile.i2p): The MuWire user manual.html, size: 53.74 KB (download with the right mouse button and select “save as”.)

[TNL]

Thank you very much for sharing

I also hope to see zlatinb here more often.

[lgillis]

Here is a first presentable PDF, but still in draft form. I used Andika as the basic font, it is easy to read and prevents misunderstandings (O0Il). The meter-long addresses could only be used with line breaks, but I made this clear. Feel free to comment, even if you think it's all useless nonsense. See above for link.

If someone with sufficient language skills would like to take over the maintenance and expansion of the handbook, they are welcome to get in touch.