Skip to content
DC* edited this page Aug 29, 2020 · 6 revisions

Description

ClientPut is used to specify an insert into Freenet of a single file. This may be provided by referring to a file on disk, including the data directly in the message, or redirecting to another key.

A filename may be specified using the TargetFilename option. This is mostly useful with CHKs. The effect is to create a single file manifest which contains only the filename given, and points to the data just inserted. Thus the provided filename becomes the last part of the URI, and must be provided when fetching the data. See Single-file manifest for details.

Example

 ClientPut
 URI=CHK@
 Metadata.ContentType=text/html
 Identifier=My Test Insert
 Verbosity=0
 MaxRetries=10
 PriorityClass=1
 GetCHKOnly=false
 Global=false
 DontCompress=false
 Codecs=LZMA
 ClientToken=Hello!!!
 UploadFrom=disk
 Filename=/home/toad/something.html
 TargetFilename=me.html
 FileHash=Base64String
 BinaryBlob=false
 CompatibilityMode=COMPAT_CURRENT
 LocalRequestOnly=false
 EndMessage
Field Possible values Mandatory Default Condition Description
URI CHK@
KSK@name
SSK@privateKey/docname-1
USK@privateKey/docname/0/
  
yes The type of key to insert. When inserting an SSK key, you explicitly specifiy the version number. For a USK key, use a zero and it should automatically use the correct version number.
Metadata.ContentType Any MIME type no application/octet-stream The MIME type of the data being inserted. For text, if charset is not specified, node should auto-detect it and force the auto-detected version
Identifier Arbitrary text string yes This is just for client to be able to identify files that have been inserted.
Verbosity Bitmask no 0 Allows additional insertion status updates beyond the standard FCPv2-PutSuccessful and FCPv2-PutFailed updates.
MaxRetries Integer -1 to 999999+? no 0 Number of times to retry if the first time doesn't work. -1 means retry forever.
PriorityClass [0..2..6] no 2 (Semi-interactive priority class) How to prioritize the insert.
GetCHKOnly [true,false] no false If set to true, it won't actually insert the data, just return the key it would generate. If the key is USK, you may want to transform it into a SSK to prevent the node spending time searching for an unused index.
Global [true,false] no false Whether the insert is visible on the global queue or not. If you set this as true, you should probably do a WatchGlobal, or you won't get any FCPv2-PutSuccessful / FCPv2-PutFailed message
DontCompress [true,false] no false Hint to node: don't try to compress the data, it's already compressed
Codecs a comma separated list of either names or ids no The node will try to compress the data with the given codec(s). If more then one codec is given the node will try to find the best in the given order. The node tells the supported codecs in the NodeHello message. This setting was introduced in 1231.
ClientToken Arbitrary string no Returned to the client in the PersistentPut message if this is a persistent request.
Persistence [connection,reboot,forever] no connection Whether the insert stays on the queue across new client connections, Freenet restarts, or forever
TargetFilename A filename (no slashes) no Extracted from URI or Filename Filename to be appended to a CHK insert. Technically it creates a one-file manifest with this filename pointing to the file being uploaded. Ignored for all types other than CHK since other types have human-readable filenames anyway. Empty means no filename.
EarlyEncode [true,false] no false See EarlyEncode
UploadFrom [direct,disk,redirect] no direct Whether the FCP message includes the actual data, just the disk filename and path, or a redirection to an existing freenet key. If you upload from disk, you have to do a TestDDARequest.
DataLength Integer from 0 to ? yes UploadFrom is direct The length of the data file being included in this FCP message
Filename The full path of a file yes UploadFrom is disk The full name and path of the file you wish to insert to Freenet
TargetURI A freenet URI yes UploadFrom is redirect This is an existing freenet URI such as KSK@sample.txt. The idea is that you insert a new key that redirects to this one.
FileHash Base64 encoded SHA256 hash no Base64 encoded SHA256 hash of the content you want the node to insert. This is only useful if you use UploadFrom=disk. This field will allow you to override any TestDDA restriction if you provide a hash of the content which should be inserted. It should be computed like this : Base64Encode(SHA256( NodeHello.identifier + '-' + Identifier + '-' + content)). This setting was introduced in 1027.
BinaryBlob [true,false] no false If true, insert a binary blob (a collection of keys used in the downloading of a specific key or site). Implies no metadata, no URI.
ForkOnCacheable [true,false] Depends on node version true Override insert behaviour: If true, fork an insert after its HTL becomes low enough for it to be cacheable. If false, don't fork the insert at this point. Inserts are not cached while their HTL is above 15, after that they can be cached, but this can be many hops because of probabilistic decrement, hence they may go over the "ideal" nodes or "sinks" where they should have been cached while they are still not allowed to, and the insert will not go back to those nodes because it's already been there. Forking deals with this by creating a new insert, which can go back over nodes we've already been to if necessary.
ExtraInsertsSingleBlock Integer >= 0 no 2 (from 1297) Insert single blocks (not blocks above splitfiles, and not blocks in splitfiles) additional times. Testing has shown that a value of 2 (3 inserts total) can dramatically improve data persistence. We are still trying to figure out why.
ExtraInsertsSplitfileHeaderBlock Integer >=0 no 2 Insert blocks above splitfiles additional times. E.g. the CHK at the top of a splitfile, the CHK you actually fetch, is a single block. The splitfile itself has redundancy but the top block doesn't. So we insert it multiple times (3 by default) to improve the number of nodes it gets stored on. Tests show this dramatically improves data persistence, we are still trying to figure out why.
CompatibilityMode [COMPAT_CURRENT,] no COMPAT_CURRENT Insert the data in a way that is identical to how older nodes inserted it, not taking advantage of improvements in the metadata format, so that we can generate the same CHK and do reinserts, so that the old keys still work. COMPAT_1250 actually uses the 1251 version of even segment splitting, but doesn't add an extra block to smaller segments (so doesn't cause pre-1250 nodes to crash); COMPAT_1250_EXACT inserts segments of exactly 128 blocks except for the last one, so inserts exactly the same as older nodes. 1251 introduces even segment splitting (with extra blocks for sub-128 block segments), 1254 introduces better even segment splitting and a variety of other changes e.g. hashes, single splitfile key. It is likely that 1255 will include further metadata changes for large files.
LocalRequestOnly [true,false] no False If true, data will be inserted into the datastore, not sent to the network. Only useful for testing, as nobody will be able to find the data; also unsafe in that it inserts local content directly to your store.
OverrideSplitfileCryptoKey 256 bit key in hex no If set, the bottom layer of any splitfiles inserted will be encrypted using this key, rather than a key derived from the hash of the content. This is useful for reinserting data that was inserted to an SSK. SSKs automatically use a random key for the bottom layer splitfile as of 1254, unless CompatibilityMode is set to an earlier version. Note that upper layers (i.e. multi-level metadata) are still encrypted according to the data hash; they are not predictable so there is no need to complicate matters.
RealTimeFlag no false Whether to fetch the data with the real-time flag set to realtime (true) or bulk (false). (since 1311)
MetadataThreshold Number of bytes (long) no -1 If >0, Freenet will try to return metadata smaller than the size given rather than a URI. This allows on-Freenet structures to have redundancy all the way up the pyramid, for instance Library's b-tree indexes. Instead of having a single CHK at the top, you have a small block of metadata which is included in the key referring to this key - which is a redundant splitfile, improving reliability. (From 1380)
EndMessage UploadFrom is not direct Indicates the end of the message. No data follows this line.
Data UploadFrom is direct Indicates the end of the message. The data follows this line. (Immediately after the newline).
Clone this wiki locally